{ "openapi": "3.0.3", "info": { "title": "BrokerPlus API (beta)", "version": "2026-08-15-beta", "description": "The BrokerPlus REST API.\n\n**This API is in beta.** Any endpoint here can change in a way that breaks your\nintegration, and it can change without notice. Build defensively: ignore a field that you\ndo not recognize, instead of failing on it. Read the changelog for every change we make.\n\nAuthenticate with `Authorization: Bearer `. A key acts as the broker who created\nit. It can do everything that broker can do in the app, and nothing more.\n\nEvery field name is `snake_case`. Every timestamp is an ISO 8601 string in UTC. Every\ncalendar date is a `YYYY-MM-DD` string, because a date column holds no time and no time\nzone." }, "servers": [ { "url": "https://api.mos.getbrokerplus.ca/v1" } ], "tags": [ { "name": "Identity", "description": "Verify a key and see who it acts as." }, { "name": "Assistant", "description": "The standing instructions a broker gives their assistant." }, { "name": "Users", "description": "The brokers in the brokerage. Resolves every broker id on this surface." }, { "name": "Teams", "description": "Broker teams. Each is owned by exactly one broker." }, { "name": "Pipelines", "description": "Deal boards and their stages. Resolves a deal's board and stage ids." }, { "name": "Contacts", "description": "People and companies in the book, with their notes and tags." }, { "name": "Leads", "description": "Inbound prospects, before they become deals." }, { "name": "Lead forms", "description": "The forms a broker puts on a website, and the leads each one brought in." }, { "name": "Deals", "description": "The mortgage pipeline, with its notes and tags." }, { "name": "Documents", "description": "Files on a deal, and short-lived download links." }, { "name": "Conditions", "description": "What a lender still needs before a deal can close." }, { "name": "Mortgage", "description": "The mortgage record on a deal: loan terms, the property, the applicants and their financials." }, { "name": "Opportunities", "description": "The book of tracked mortgages, with the penalty to break and the savings from moving." }, { "name": "Submissions", "description": "Deals sent to a lender, and what the lender answered." }, { "name": "Compliance", "description": "The brokerage's compliance setup: package templates, the compliance program, retention, monitoring alerts and policies." }, { "name": "Lenders", "description": "The lenders a brokerage places business with." }, { "name": "Rates", "description": "The rates the broker and the brokerage set on the Rates page, as a PERCENT." }, { "name": "Appointments", "description": "The broker's calendar." }, { "name": "Scheduling", "description": "Meeting types, their open times, and bookings made into them." }, { "name": "Communications", "description": "Email, calls and messages on a deal or a contact." }, { "name": "Calls", "description": "The call log, with transcripts and recaps. Log a call from another phone system or recorder." }, { "name": "Call lists", "description": "Lists of people to phone, worked one row at a time, and the call scripts read on those calls." }, { "name": "Tags", "description": "The brokerage's tag vocabularies. Contacts and deals have separate ones." }, { "name": "Tasks", "description": "The action queue. Read, edit, complete, cancel, and reopen, with notes." }, { "name": "Campaigns", "description": "Newsletters and mass messages, their audiences, and who opened or opted out." }, { "name": "Templates", "description": "The email and text templates in the Pulse library, and the merge fields they can use." }, { "name": "Automations", "description": "Pulse automations: what starts each one, and the messages it sends." }, { "name": "Equity reports", "description": "The monthly reports past clients receive, and what each client did with one." }, { "name": "Retention signals", "description": "Why to reach a past client now: an equity drop or a date of theirs, and the broker's date triggers." }, { "name": "Reports", "description": "The pipeline and funded volume, as the Business pages show them, and the report builder: report templates and bulk report runs." }, { "name": "Data hub", "description": "Exports of the broker's data, and the imports that bring a book into BrokerPlus." }, { "name": "Planning", "description": "What a broker builds to advise a client: mortgage plans, lender offers and their side-by-side comparison, deal scenarios, and strategy analyses." }, { "name": "Referral partners", "description": "Who sends the broker business, what it was worth, and what the broker sent back." }, { "name": "Client surveys", "description": "NPS surveys sent to clients, their scores, and the alert rules a score sets off." }, { "name": "Compliance forms", "description": "The forms a broker emails a client to fill in and sign: the PEP declaration and consent forms." }, { "name": "Client tracker", "description": "The stages a client sees on their hub, in the broker's words, and the stages each deal reached." }, { "name": "Intakes", "description": "The application a client fills in themselves: the standing link anybody can start from, and one intake per client." }, { "name": "Request templates", "description": "The broker's request library: the templates a broker builds to ask clients for answers, documents and signatures." }, { "name": "Webhooks", "description": "Push notifications for 21 event types." }, { "name": "Changes", "description": "An ordered log of every change to the records, for a sync that misses nothing." }, { "name": "Sandbox", "description": "A test brokerage with synthetic data, where nothing is sent to a real person." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from Settings -> Developer." } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Who am I", "description": "Returns the organization, the broker the key acts as, and the key itself. Use it to verify setup.", "tags": [ "Identity" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string", "description": "The brokerage this key reads and writes." }, "name": { "type": "string", "description": "Brokerage name as it appears in BrokerPlus." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "The only organization this key can ever see." }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "The broker the key acts as." }, "name": { "nullable": true, "description": "Display name, if the broker has set one.", "type": "string" }, "email": { "type": "string", "description": "The broker's sign-in email." }, "role": { "type": "string", "description": "Their role in the brokerage, e.g. `admin` or `member`." } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false, "description": "A key has exactly the reach of this broker. It cannot do more, and does not do less." }, "api_key": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifies the key itself, for your own logging." }, "name": { "type": "string", "description": "The label given when the key was created." }, "read_only": { "type": "boolean", "description": "True if this key can only read. A read-only key answers `GET` and refuses every other method with `403 READ_ONLY_KEY`. Set when the key was created and cannot be changed afterward." }, "limits": { "type": "array", "items": { "type": "string" }, "description": "The limits set on this key when it was created. Each limit removes access and none adds it, so a key never does more than its broker. `read_only`: only `GET`. `leads_only`: only the lead endpoints, `GET /v1/me` and `GET /v1/custom-fields`; converting a lead is refused. `no_sending`: refuses every call that puts something in front of a client, such as booking a meeting, scheduling a campaign or emailing an intake. `no_documents`: refuses every document endpoint and message attachments. A refused call returns `403` with code `KEY_LIMITED` (`READ_ONLY_KEY` for `read_only`) and the limit in `details.limit`. An empty list means no limits." }, "last_used_at": { "nullable": true, "description": "Last authenticated call. Updated at most once a minute.", "type": "string" }, "created_at": { "type": "string", "description": "When the key was created." }, "team": { "nullable": true, "description": "The team this key reads and writes. Set when the key was made. Null for a key made by a brokerage admin who has no team: that key follows the admin's current team.", "type": "object", "properties": { "id": { "type": "string", "description": "The team's identifier." }, "name": { "type": "string", "description": "The team's name as it appears in BrokerPlus." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "read_only", "limits", "last_used_at", "created_at", "team" ], "additionalProperties": false, "description": "The key you authenticated with. The secret is never echoed back." } }, "required": [ "organization", "user", "api_key" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/hours": { "get": { "operationId": "getMyHours", "summary": "Get the broker's hours", "description": "The time zone, phone hours, and booking hours of the key's broker, as Settings > Profile shows them. Open booking times come from these hours unless a meeting type has its own.", "tags": [ "Scheduling" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "timezone": { "nullable": true, "description": "The broker's IANA time zone, e.g. `America/Toronto`. Null uses the brokerage time zone.", "type": "string" }, "business_hours": { "nullable": true, "description": "The hours when the broker's BrokerPlus phone line rings through. Null uses Monday to Friday, 9:00 to 17:00.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "booking_hours": { "nullable": true, "description": "The hours when clients can book the broker. Null uses `business_hours`. A meeting type with its own `availability_hours` uses those instead.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } } }, "required": [ "timezone", "business_hours", "booking_hours" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateMyHours", "summary": "Update the broker's hours", "description": "Changes the time zone, phone hours, or booking hours of the key's broker. A key changes only its own broker's hours. Send all seven days of a schedule. A change applies to the open times offered after it. Booked appointments keep their times.", "tags": [ "Scheduling" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "description": "An IANA time zone, e.g. `America/Vancouver`. Send null to use the brokerage time zone.", "nullable": true, "type": "string" }, "business_hours": { "description": "The phone hours, one entry for each day. Send null to use Monday to Friday, 9:00 to 17:00.", "nullable": true, "minItems": 7, "maxItems": 7, "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. `540` is 9:00." }, "end_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. It must be after `start_minute`." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day, at most six. They must not overlap. Send an empty list for a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "booking_hours": { "description": "The booking hours, one entry for each day. Send null to make bookings use `business_hours`.", "nullable": true, "minItems": 7, "maxItems": 7, "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. `540` is 9:00." }, "end_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. It must be after `start_minute`." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day, at most six. They must not overlap. Send an empty list for a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "timezone": { "nullable": true, "description": "The broker's IANA time zone, e.g. `America/Toronto`. Null uses the brokerage time zone.", "type": "string" }, "business_hours": { "nullable": true, "description": "The hours when the broker's BrokerPlus phone line rings through. Null uses Monday to Friday, 9:00 to 17:00.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "booking_hours": { "nullable": true, "description": "The hours when clients can book the broker. Null uses `business_hours`. A meeting type with its own `availability_hours` uses those instead.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the broker's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } } }, "required": [ "timezone", "business_hours", "booking_hours" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The time zone is not an IANA time zone, or a window ends before it starts or overlaps another (VALIDATION_ERROR, INVALID_TIMEZONE, INVALID_BUSINESS_HOURS, INVALID_BOOKING_HOURS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/blocked-days": { "get": { "operationId": "listMyBlockedDays", "summary": "List the broker's blocked days", "description": "The days when clients cannot book the key's broker, on top of the weekly hours, earliest first. This is the Blocked days list in Settings > Booking.", "tags": [ "Scheduling" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "A day with no bookings, as `YYYY-MM-DD` in the broker's time zone." }, "note": { "nullable": true, "description": "The broker's own note for the day, e.g. `Vacation`.", "type": "string" } }, "required": [ "date", "note" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "blockMyDays", "summary": "Block days", "description": "Blocks one day or a range of days for the key's broker. Clients cannot book the broker on those days. Appointments already booked on them stay. A day that is already blocked gets the new note. Returns the days that the request blocked.", "tags": [ "Scheduling" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The first day to block, as `YYYY-MM-DD`." }, "to": { "description": "The last day to block, as `YYYY-MM-DD`. Omit it to block one day. A range is at most 90 days.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "note": { "description": "A note for the days, e.g. `Vacation`.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "from" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "A day with no bookings, as `YYYY-MM-DD` in the broker's time zone." }, "note": { "nullable": true, "description": "The broker's own note for the day, e.g. `Vacation`.", "type": "string" } }, "required": [ "date", "note" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "A date is not a real day, `to` is before `from`, or the range is more than 90 days (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/blocked-days/{date}": { "delete": { "operationId": "unblockMyDay", "summary": "Unblock a day", "description": "Lets clients book the key's broker on the day again. `date` is `YYYY-MM-DD`. The `id` in the response is the date.", "tags": [ "Scheduling" ], "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The day is not blocked (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/email-signature": { "get": { "operationId": "getMyEmailSignature", "summary": "Get the broker's email signature", "description": "The email signature of the key's broker, as HTML. This is the signature in Settings > Profile.", "tags": [ "Identity" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "html": { "type": "string", "description": "The broker's email signature, as HTML. BrokerPlus adds it to the email the broker sends. An empty string is no signature." } }, "required": [ "html" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateMyEmailSignature", "summary": "Update the broker's email signature", "description": "Replaces the email signature of the key's broker. A key changes only its own broker's signature. The change sends nothing. It applies to the email the broker sends after it, from each inbox that does not have a signature of its own.", "tags": [ "Identity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "The signature as HTML, at most 512 KB. BrokerPlus removes scripts, styles, and other markup that email clients do not show, and returns what it keeps. Send an empty string to remove the signature." } }, "required": [ "html" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "html": { "type": "string", "description": "The broker's email signature, as HTML. BrokerPlus adds it to the email the broker sends. An empty string is no signature." } }, "required": [ "html" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`html` is more than 512 KB (INVALID_EMAIL_SIGNATURE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/users": { "get": { "operationId": "listUsers", "summary": "List brokers", "description": "The brokers in this brokerage. Resolve the `owner_id`, `assigned_broker_id` and `assignee_user_id` you get back on other resources. Inactive brokers are excluded unless you ask for them.", "tags": [ "Users" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send `true` to include deactivated brokers. Their records still reference them." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "user", "description": "The type of this record. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "Stable identifier. This is what `owner_id` and `assigned_broker_id` point at." }, "name": { "nullable": true, "description": "Display name, if the broker has set one.", "type": "string" }, "email": { "type": "string", "description": "Their sign-in email, and where BrokerPlus writes to them." }, "role": { "type": "string", "enum": [ "admin", "member", "compliance", "viewer" ], "description": "`admin` is a principal broker. `viewer` is read-only inside BrokerPlus." }, "is_active": { "type": "boolean", "description": "False once a broker is deactivated. Their records stay, they cannot sign in." }, "timezone": { "nullable": true, "description": "The broker's time zone, as an IANA name such as `America/Toronto`. Null when they have not set one.", "type": "string" }, "license_number": { "nullable": true, "description": "The broker's licence number, as the regulator issued it. Null when nobody recorded it.", "type": "string" }, "licenses": { "type": "array", "items": { "type": "object", "properties": { "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province or territory that issued the licence, e.g. `ON`." }, "class": { "nullable": true, "description": "What the licence lets the broker do in that province. `unlicensed` means that the broker said they hold none. Null when nobody recorded a class.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "expires_on": { "nullable": true, "description": "The day the licence expires. Null when nobody recorded it.", "type": "string" } }, "required": [ "province", "class", "expires_on" ], "additionalProperties": false }, "description": "The mortgage licences the broker holds, one for each province. Empty when the broker recorded none. This is what the regulator lets them do, not what they can do in BrokerPlus." }, "created_at": { "type": "string", "description": "When the broker was added to the brokerage." }, "updated_at": { "type": "string", "description": "Last change to their profile." } }, "required": [ "object", "id", "name", "email", "role", "is_active", "timezone", "license_number", "licenses", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/users/{id}": { "get": { "operationId": "getUser", "summary": "Retrieve a broker", "description": "A single broker by id.", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "user", "description": "The type of this record. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "Stable identifier. This is what `owner_id` and `assigned_broker_id` point at." }, "name": { "nullable": true, "description": "Display name, if the broker has set one.", "type": "string" }, "email": { "type": "string", "description": "Their sign-in email, and where BrokerPlus writes to them." }, "role": { "type": "string", "enum": [ "admin", "member", "compliance", "viewer" ], "description": "`admin` is a principal broker. `viewer` is read-only inside BrokerPlus." }, "is_active": { "type": "boolean", "description": "False once a broker is deactivated. Their records stay, they cannot sign in." }, "timezone": { "nullable": true, "description": "The broker's time zone, as an IANA name such as `America/Toronto`. Null when they have not set one.", "type": "string" }, "license_number": { "nullable": true, "description": "The broker's licence number, as the regulator issued it. Null when nobody recorded it.", "type": "string" }, "licenses": { "type": "array", "items": { "type": "object", "properties": { "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province or territory that issued the licence, e.g. `ON`." }, "class": { "nullable": true, "description": "What the licence lets the broker do in that province. `unlicensed` means that the broker said they hold none. Null when nobody recorded a class.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "expires_on": { "nullable": true, "description": "The day the licence expires. Null when nobody recorded it.", "type": "string" } }, "required": [ "province", "class", "expires_on" ], "additionalProperties": false }, "description": "The mortgage licences the broker holds, one for each province. Empty when the broker recorded none. This is what the regulator lets them do, not what they can do in BrokerPlus." }, "created_at": { "type": "string", "description": "When the broker was added to the brokerage." }, "updated_at": { "type": "string", "description": "Last change to their profile." } }, "required": [ "object", "id", "name", "email", "role", "is_active", "timezone", "license_number", "licenses", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines": { "get": { "operationId": "listPipelines", "summary": "List pipelines", "description": "The brokerage's deal boards, each with its stages in order. This is how a deal's `board_id` and `stage_id` become readable.", "tags": [ "Pipelines" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createPipeline", "summary": "Create a pipeline", "description": "Adds a pipeline to your team, the same as Add pipeline in BrokerPlus. The key's broker owns it. Without `stages`, it starts with the standard stages. The new pipeline goes after your team's other pipelines.", "tags": [ "Pipelines" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the brokerage calls the pipeline." }, "description": { "description": "Free-text note on what the pipeline is for.", "nullable": true, "type": "string", "maxLength": 2000 }, "allowed_deal_types": { "description": "Deal types that land on this pipeline by default. Omit it for no preference.", "type": "array", "items": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] } }, "stages": { "description": "The stages, in order. Omit it to start with the standard stages.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9_-]+$", "description": "Machine-readable slug, unique within the pipeline. You cannot change it later. A key of an archived stage restores that stage." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name shown to brokers." }, "description": { "description": "What is true of a deal in this stage, in the brokerage's words.", "nullable": true, "type": "string", "maxLength": 1000 }, "color": { "description": "Swatch for the column, as a hex color.", "nullable": true, "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "position": { "description": "Order within the pipeline. Omit it to add the stage after the last one.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exclude_from_book": { "description": "`true` for a stage that holds paid-out mortgages. Defaults to `false`.", "type": "boolean" }, "stops_automated_outreach": { "description": "`true` stops all automated messages to the clients of a deal in this stage. Only a broker who can change automations can set it. Defaults to `false`.", "type": "boolean" }, "requirements": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` requires a deal value, `checkpoint` a checklist step, `custom_field` one of your deal custom fields, and `none` clears the earlier stages' requirements." }, "key": { "description": "Required for `field`, `checkpoint`, and `custom_field`. A field key must be one BrokerPlus knows, a participant must be one of your seats, a checkpoint must be a step on the pipeline team's checklist, and a custom field must be one of your live deal custom fields.", "type": "string", "minLength": 1, "maxLength": 200 }, "label": { "description": "For a `checkpoint`: the step's name.", "type": "string", "minLength": 1, "maxLength": 60 }, "required": { "description": "For a `checkpoint`: `true` stops the move until the step is done. Defaults to `false`. A `mode` you send wins over it.", "type": "boolean" }, "mode": { "description": "For a `field`, `checkpoint`, or `custom_field`: `cumulative` applies the requirement to this stage and every later stage. `this_stage` applies it to this stage only. `optional` asks for it but does not stop the move. Defaults to `cumulative`, or for a `checkpoint` to what `required` says.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "description": "Apply the requirement only to these deal types. Omit it to apply it to every deal type.", "maxItems": 40, "type": "array", "items": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] } } }, "required": [ "kind" ], "additionalProperties": false }, "description": "The full list of what a deal must have before it can move into the stage. It replaces the list the stage has. Send an empty list to require nothing more than the earlier stages." } }, "required": [ "key", "label" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Two stages have the same key (DUPLICATE_KEY), or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not on a team (NO_TEAM), or a stage stops automated messages and the broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines/{id}": { "get": { "operationId": "getPipeline", "summary": "Retrieve a pipeline", "description": "A single pipeline and its stages.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updatePipeline", "summary": "Update a pipeline", "description": "Changes the name, description, or default deal types of a pipeline. Use the stage endpoints for its stages.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "What the brokerage calls the pipeline.", "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "Free-text note. Send null to clear it.", "nullable": true, "type": "string", "maxLength": 2000 }, "allowed_deal_types": { "description": "Deal types that land on this pipeline by default. Send an empty list for no preference.", "type": "array", "items": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline is not one of your team's live pipelines (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deletePipeline", "summary": "Delete a pipeline", "description": "Removes a pipeline, the same as Delete in BrokerPlus. When deals are on the pipeline, BrokerPlus refuses the delete unless you send `archive_deals=true`. With it, the deals go to the archive with the pipeline, the same as when a broker confirms the delete. You cannot delete the broker's last pipeline.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "archive_deals", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send `true` to archive the deals on the pipeline with it. Without it, a pipeline that has deals is not deleted." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline is not one of your team's live pipelines (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Deals are on the pipeline and `archive_deals` is not `true` (PIPELINE_IN_USE), or it is the broker's last pipeline (LAST_BOARD).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines/reorder": { "post": { "operationId": "reorderPipelines", "summary": "Put pipelines in order", "description": "Sets the order of your team's pipelines, the same as a drag of the pipeline tabs. A new deal lands on the first pipeline that accepts its type, so the order also changes where new deals go. Returns the pipelines in the new order.", "tags": [ "Pipelines" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Every pipeline id of your team, in the new order. The first pipeline that accepts a deal type is where a new deal of that type lands." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "An id is in the list two times (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "A pipeline is not one of your team's live pipelines (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines/{id}/stages": { "post": { "operationId": "createPipelineStage", "summary": "Add a stage to a pipeline", "description": "Adds a column to a pipeline. A `key` of an archived stage restores that stage, so the deals that name it show in it again. Returns the pipeline.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9_-]+$", "description": "Machine-readable slug, unique within the pipeline. You cannot change it later. A key of an archived stage restores that stage." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name shown to brokers." }, "description": { "description": "What is true of a deal in this stage, in the brokerage's words.", "nullable": true, "type": "string", "maxLength": 1000 }, "color": { "description": "Swatch for the column, as a hex color.", "nullable": true, "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "position": { "description": "Order within the pipeline. Omit it to add the stage after the last one.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exclude_from_book": { "description": "`true` for a stage that holds paid-out mortgages. Defaults to `false`.", "type": "boolean" }, "stops_automated_outreach": { "description": "`true` stops all automated messages to the clients of a deal in this stage. Only a broker who can change automations can set it. Defaults to `false`.", "type": "boolean" }, "requirements": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` requires a deal value, `checkpoint` a checklist step, `custom_field` one of your deal custom fields, and `none` clears the earlier stages' requirements." }, "key": { "description": "Required for `field`, `checkpoint`, and `custom_field`. A field key must be one BrokerPlus knows, a participant must be one of your seats, a checkpoint must be a step on the pipeline team's checklist, and a custom field must be one of your live deal custom fields.", "type": "string", "minLength": 1, "maxLength": 200 }, "label": { "description": "For a `checkpoint`: the step's name.", "type": "string", "minLength": 1, "maxLength": 60 }, "required": { "description": "For a `checkpoint`: `true` stops the move until the step is done. Defaults to `false`. A `mode` you send wins over it.", "type": "boolean" }, "mode": { "description": "For a `field`, `checkpoint`, or `custom_field`: `cumulative` applies the requirement to this stage and every later stage. `this_stage` applies it to this stage only. `optional` asks for it but does not stop the move. Defaults to `cumulative`, or for a `checkpoint` to what `required` says.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "description": "Apply the requirement only to these deal types. Omit it to apply it to every deal type.", "maxItems": 40, "type": "array", "items": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] } } }, "required": [ "kind" ], "additionalProperties": false }, "description": "The full list of what a deal must have before it can move into the stage. It replaces the list the stage has. Send an empty list to require nothing more than the earlier stages." } }, "required": [ "key", "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A requirement names a field, participant, role, or step that your brokerage does not have (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The stage stops automated messages and the broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline is not one of your team's live pipelines (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live stage of the pipeline has this key (DUPLICATE_KEY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines/{id}/stages/reorder": { "post": { "operationId": "reorderPipelineStages", "summary": "Put a pipeline's stages in order", "description": "Sets the order of the columns of a pipeline. Send every stage of the pipeline. Returns the pipeline.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "Every stage id of this pipeline, in the new order, first to last." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "An id is in the list two times, or a stage is missing from the list (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline or a stage is not one of your team's (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pipelines/{id}/stages/{stage_id}": { "patch": { "operationId": "updatePipelineStage", "summary": "Update a stage", "description": "Changes a column of a pipeline, and what a deal must have before it can move into it. `requirements` replaces the full list. `GET /deals/{id}/stage-requirements` shows what a deal still needs. Returns the pipeline.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "stage_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "description": "Display name shown to brokers.", "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "description": "What is true of a deal in this stage. Send null to clear it.", "nullable": true, "type": "string", "maxLength": 1000 }, "color": { "description": "Swatch for the column, as a hex color. Send null to clear it.", "nullable": true, "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "exclude_from_book": { "description": "`true` for a stage that holds paid-out mortgages.", "type": "boolean" }, "stops_automated_outreach": { "description": "`true` stops all automated messages to the clients of the deals in this stage, including the deals in it now. `false` starts them again. Only a broker who can change automations can change it.", "type": "boolean" }, "requirements": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` requires a deal value, `checkpoint` a checklist step, `custom_field` one of your deal custom fields, and `none` clears the earlier stages' requirements." }, "key": { "description": "Required for `field`, `checkpoint`, and `custom_field`. A field key must be one BrokerPlus knows, a participant must be one of your seats, a checkpoint must be a step on the pipeline team's checklist, and a custom field must be one of your live deal custom fields.", "type": "string", "minLength": 1, "maxLength": 200 }, "label": { "description": "For a `checkpoint`: the step's name.", "type": "string", "minLength": 1, "maxLength": 60 }, "required": { "description": "For a `checkpoint`: `true` stops the move until the step is done. Defaults to `false`. A `mode` you send wins over it.", "type": "boolean" }, "mode": { "description": "For a `field`, `checkpoint`, or `custom_field`: `cumulative` applies the requirement to this stage and every later stage. `this_stage` applies it to this stage only. `optional` asks for it but does not stop the move. Defaults to `cumulative`, or for a `checkpoint` to what `required` says.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "description": "Apply the requirement only to these deal types. Omit it to apply it to every deal type.", "maxItems": 40, "type": "array", "items": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] } } }, "required": [ "kind" ], "additionalProperties": false }, "description": "The full list of what a deal must have before it can move into the stage. It replaces the list the stage has. Send an empty list to require nothing more than the earlier stages." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pipeline", "description": "The type of this record. Always `pipeline`.", "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `board_id` points at." }, "name": { "type": "string", "description": "What the brokerage calls this pipeline." }, "description": { "nullable": true, "description": "Free-text note on what the pipeline is for.", "type": "string" }, "allowed_deal_types": { "type": "array", "items": { "type": "string" }, "description": "Deal types that land on this pipeline by default. The field does not restrict moves. Empty means no preference." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order among the brokerage's pipelines, ascending." }, "key": { "nullable": true, "description": "Which of the standard pipelines this is: `leads`, `preapproval`, `approval`, `renewals`, `reverse_mortgage`, or `historical` for funded and past deals. Null on a pipeline the brokerage made.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker whose pipeline this is. Resolve against `GET /users`." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pipeline_stage", "description": "The type of this record. Always `pipeline_stage`.", "type": "string", "enum": [ "pipeline_stage" ] }, "id": { "type": "string", "description": "Stable identifier. This is what a deal's `stage_id` points at." }, "key": { "type": "string", "description": "Machine-readable slug, unique within the pipeline. Branch on this, not on `label`." }, "label": { "type": "string", "description": "Display name shown to brokers. Renameable, so do not key off it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the pipeline, ascending. Not necessarily contiguous." }, "color": { "nullable": true, "description": "Swatch used in the BrokerPlus UI. Cosmetic.", "type": "string" }, "description": { "nullable": true, "description": "What is true of a deal in this stage, in the brokerage's words. Null when nobody wrote one.", "type": "string" }, "exclude_from_book": { "type": "boolean", "description": "`true` for a stage that holds paid-out mortgages. A deal here drops out of renewal and refinance outreach." }, "stops_automated_outreach": { "type": "boolean", "description": "`true` when a deal in this stage stops all automated messages to its clients." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field", "none" ], "description": "`field` is a value the deal must have, `checkpoint` is a step on the team's checklist, `custom_field` is one of your deal custom fields that must be filled in, and `none` lets a deal enter the stage with nothing filled in." }, "key": { "nullable": true, "description": "What is required: a deal field such as `property.purchase_price`, a participant such as `participants.lawyer`, a checklist step key, or a custom field key. Null when `kind` is `none`.", "type": "string" }, "label": { "nullable": true, "description": "The checklist step's name when the stage was set. Null for other kinds.", "type": "string" }, "required": { "nullable": true, "description": "For a `checkpoint`: `true` when the step must be done before the move. `false` is the same as `mode` `optional`. Null for other kinds.", "type": "boolean" }, "mode": { "nullable": true, "description": "`cumulative` stops the move into this stage and every later stage until the requirement is met. `this_stage` stops the move into this stage only. `optional` asks for it when a broker moves the deal into this stage, but does not stop the move. Null when `kind` is `none`.", "type": "string", "enum": [ "cumulative", "this_stage", "optional" ] }, "deal_types": { "type": "array", "items": { "type": "string" }, "description": "The deal types the requirement applies to. Empty means every deal type." } }, "required": [ "kind", "key", "label", "required", "mode", "deal_types" ], "additionalProperties": false }, "description": "What a deal must have before it can move into this stage. A stage also requires what the earlier stages require, unless it has a `none` requirement. Empty when the stage adds nothing." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "Last change to the stage." } }, "required": [ "object", "id", "key", "label", "position", "color", "description", "exclude_from_book", "stops_automated_outreach", "requirements", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Its stages, in board order. A deal sits on exactly one." }, "created_at": { "type": "string", "description": "When the pipeline was created." }, "updated_at": { "type": "string", "description": "Last change to the pipeline or its stages." } }, "required": [ "object", "id", "name", "description", "allowed_deal_types", "position", "key", "broker_user_id", "stages", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A requirement names a field, participant, role, or step that your brokerage does not have (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The change starts or stops automated messages and the broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline or the stage is not one of your team's (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deletePipelineStage", "summary": "Delete a stage", "description": "Archives a column of a pipeline. BrokerPlus refuses it while an active deal is in the stage: move those deals first. To restore the stage, add a stage with the same `key`.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "stage_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The pipeline or the stage is not one of your team's (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Active deals are in the stage. The message gives the count (STAGE_IN_USE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Everyone in the brokerage book: leads, clients, partners and co-brokers. Use `updated_since` to sync incrementally rather than re-reading page 1.", "tags": [ "Contacts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Exact email address. Case and surrounding spaces are ignored. Matches the contact's main email or any additional email. No match returns an empty list, not 404." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Phone number in any format. Matches on the last 10 digits, so `+1 (587) 555-1234` and `5875551234` find the same contact. Matches the main phone or any additional phone." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text search over the name, nickname, company, email and phone. Every word must match part of one of them. The same search as the search bar in BrokerPlus." }, { "name": "custom_field", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Filter by a contact custom field: `custom_field[]=`, for example `custom_field[lead_source]=Google`. The value takes the same text as a write. An empty value finds records with no answer. Send up to 10; a record must match all of them. Get the keys from `GET /v1/custom-fields?entity=contact`.", "style": "deepObject", "explode": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "A `phone` with no digits, a `custom_field` key the brokerage does not have, or a value that does not fit the field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContact", "summary": "Create a contact", "description": "One of `first_name` or `company_name` is required. The API does not check the book for a duplicate unless you ask it to with `check_duplicates`.", "tags": [ "Contacts" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Defaults to `individual`.", "type": "string", "enum": [ "individual", "company" ] }, "types": { "description": "Defaults to `[\"lead\"]`.", "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] } }, "first_name": { "description": "Given name. Expected on an individual.", "type": "string", "minLength": 1, "maxLength": 200 }, "last_name": { "description": "Family name.", "nullable": true, "type": "string", "maxLength": 200 }, "company_name": { "description": "Business name. Expected on a company.", "nullable": true, "type": "string", "maxLength": 200 }, "email": { "description": "Must be a valid address if provided.", "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "Stored as sent. Any format is accepted.", "nullable": true, "type": "string", "maxLength": 40 }, "nickname": { "description": "The name the person goes by.", "nullable": true, "type": "string", "maxLength": 200 }, "phone_extension": { "description": "The extension to dial after `phone`.", "nullable": true, "type": "string", "maxLength": 16 }, "date_of_birth": { "description": "Date of birth, `YYYY-MM-DD`.", "nullable": true, "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "check_duplicates": { "description": "Default `false`. Set it to `true` to check the book first. The API then refuses the create when a contact has the same email address, or the same first and last name. It returns `409 DUPLICATE_CONTACT`, and the matches are in `details`. For a safe retry, use `Idempotency-Key` instead.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "You sent `check_duplicates: true`, and a contact with the same email address or the same first and last name is already in the book (DUPLICATE_CONTACT). The matches are in `details.matches`. The API also returns 409 when the brokerage keeps each person on one team and another team already has this person; then `details.matches` lists only the matches on the broker's own team, and the create cannot be retried with `check_duplicates: false`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Retrieve a contact", "description": "A single contact by id. Returns 404 if it belongs to another brokerage. A contact that was merged into another returns 410 with the other contact's id.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "410": { "description": "The contact was merged into another (CONTACT_MERGED). `details.merged_into_id` is the contact it became. Store that id instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Only the fields you send are changed.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Defaults to `individual`.", "type": "string", "enum": [ "individual", "company" ] }, "types": { "description": "Defaults to `[\"lead\"]`.", "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] } }, "first_name": { "description": "Given name. Expected on an individual.", "type": "string", "minLength": 1, "maxLength": 200 }, "last_name": { "description": "Family name.", "nullable": true, "type": "string", "maxLength": 200 }, "company_name": { "description": "Business name. Expected on a company.", "nullable": true, "type": "string", "maxLength": 200 }, "email": { "description": "Must be a valid address if provided.", "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "Stored as sent. Any format is accepted.", "nullable": true, "type": "string", "maxLength": 40 }, "nickname": { "description": "The name the person goes by.", "nullable": true, "type": "string", "maxLength": 200 }, "phone_extension": { "description": "The extension to dial after `phone`.", "nullable": true, "type": "string", "maxLength": 16 }, "date_of_birth": { "description": "Date of birth, `YYYY-MM-DD`.", "nullable": true, "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "language": { "description": "The language to write and speak to this person in: `en`. Send null to go back to no stated preference.", "nullable": true, "type": "string", "enum": [ "en" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/duplicates": { "get": { "operationId": "listContactDuplicates", "summary": "List duplicate contacts", "description": "The sets of contacts that look like the same person, as the Duplicates page shows them: the same email, the same phone, or the same name. Merge a set with `POST /contacts/{id}/merge`. A set the broker marked as not a duplicate is not listed. `updated_since` returns the sets with a contact changed at or after it. A set has no position to resume after, so `after_id` gets `400 VALIDATION_ERROR`: page with `page`.", "tags": [ "Contacts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "match_key": { "type": "string", "enum": [ "email", "phone", "name" ], "description": "What the contacts share: an email address, a phone number, or a first and last name." }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The contact." }, "name": { "type": "string", "description": "The contact's name, for display." }, "email": { "nullable": true, "description": "The contact's primary email.", "type": "string" }, "phone": { "nullable": true, "description": "The contact's primary phone.", "type": "string" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What the contact is to the brokerage." }, "deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The deals the contact is on. Keep the contact with the most, usually." }, "created_at": { "type": "string", "description": "When the contact was created." } }, "required": [ "id", "name", "email", "phone", "types", "deal_count", "created_at" ], "additionalProperties": false }, "description": "Two or more contacts that look like the same person, oldest first." } }, "required": [ "match_key", "contacts" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/merge": { "post": { "operationId": "mergeContact", "summary": "Merge contacts into one", "description": "Merges the contacts in `duplicate_ids` into this contact, the same as Merge on the Duplicates page. Their deals, notes, documents, tasks and history move to this contact, which survives. The duplicates are retired, and `GET /contacts/{id}` on one of them returns 410 with this contact's id. A merge cannot be undone. Returns the merged contact.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "duplicate_ids": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string" }, "description": "The contacts to merge into the contact in the path. Their deals, notes, documents and history move to it, and they are retired." }, "fields": { "description": "The values the merged contact keeps. Leave a field out to keep the value BrokerPlus picks.", "type": "object", "properties": { "first_name": { "description": "The first name to keep.", "nullable": true, "type": "string", "maxLength": 120 }, "last_name": { "description": "The last name to keep.", "nullable": true, "type": "string", "maxLength": 120 }, "company_name": { "description": "The business name to keep.", "nullable": true, "type": "string", "maxLength": 200 }, "email": { "description": "The primary email to keep. The others stay as extra emails.", "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "The primary phone to keep. The others stay as extra phones.", "nullable": true, "type": "string", "maxLength": 40 } }, "additionalProperties": false } }, "required": [ "duplicate_ids" ], "additionalProperties": false, "description": "The contacts to merge into this one." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "An id is repeated, is this contact's own, or is already merged away (VALIDATION_ERROR, ALREADY_MERGED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "This contact or one in `duplicate_ids` is not in your brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Two of the contacts hold records that cannot be combined. Merge them in BrokerPlus (MERGE_CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/archive": { "post": { "operationId": "archiveContact", "summary": "Archive a contact", "description": "Takes the contact out of the book, the same as Archive on the contact page. The contact keeps their history, and an import or a new lead with the same email finds them. Archiving an archived contact also succeeds. Returns the contact.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/unarchive": { "post": { "operationId": "unarchiveContact", "summary": "Restore an archived contact", "description": "Puts an archived contact back in the book. Restoring a contact in the book also succeeds. Returns the contact.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact", "description": "The type of this record. Always `contact`.", "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "description": "Stable identifier. Safe to store as your foreign key." }, "kind": { "type": "string", "enum": [ "individual", "company" ], "description": "A person or a business. Decides which name fields are set." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "lead", "client", "partner", "co_broker" ] }, "description": "What this contact is to the brokerage. A contact can be several at once." }, "first_name": { "nullable": true, "description": "Given name. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "Family name. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "Business name. Null on an individual.", "type": "string" }, "email": { "nullable": true, "description": "Primary email, if one is on file.", "type": "string" }, "phone": { "nullable": true, "description": "Primary phone, as entered. Not normalized to E.164.", "type": "string" }, "owner_id": { "nullable": true, "description": "The broker who owns this contact. Null means brokerage-shared.", "type": "string" }, "owner_name": { "nullable": true, "description": "The owning broker's name. Null when the contact is brokerage-shared.", "type": "string" }, "relationship_status": { "type": "string", "enum": [ "active", "ended", "unknown" ], "description": "Whether the brokerage still considers this an active relationship." }, "nickname": { "nullable": true, "description": "The name the person goes by, e.g. `Bob` for Robert.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "Date of birth, `YYYY-MM-DD`.", "type": "string" }, "phone_extension": { "nullable": true, "description": "The extension to dial after `phone`.", "type": "string" }, "language": { "nullable": true, "description": "The language BrokerPlus writes and speaks to this person in, e.g. `en`. Null when nobody has said, which is not the same as English: each surface then falls back to its own default.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker this person is assigned to work with, when it is not the owner. Resolve against `GET /users/{id}`.", "type": "string" }, "not_a_borrower": { "type": "boolean", "description": "True when the broker has said this person is not a borrower, e.g. a realtor who once appeared on a file. It keeps `lead` and `client` off `types`." }, "is_entity": { "type": "boolean", "description": "True when the contact is a legal entity, e.g. a holding company, for compliance." }, "opt_out_milestones": { "type": "boolean", "description": "True when the person is left out of milestone greetings, such as a birthday or a mortgage anniversary." }, "created_via": { "nullable": true, "description": "How the person got into the book: `manual` (a broker, or this API), `import`, `form`, `inbound_email`, a call (`voice`, `telephony`), and so on. Null for contacts that predate the record.", "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ] }, "archived_at": { "nullable": true, "description": "When the broker archived the contact. Null for a contact in the book. An archived contact is in no list. Restore it with `POST /contacts/{id}/unarchive`.", "type": "string" }, "created_at": { "type": "string", "description": "When the contact was first created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "kind", "types", "first_name", "last_name", "company_name", "email", "phone", "owner_id", "owner_name", "relationship_status", "nickname", "date_of_birth", "phone_extension", "language", "assigned_broker_id", "not_a_borrower", "is_entity", "opt_out_milestones", "created_via", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/methods": { "get": { "operationId": "listContactMethods", "summary": "List a contact's extra emails, phones and social profiles", "description": "The ways to reach a contact beyond the primary `email` and `phone` on the contact: extra emails, phones and fax numbers, and social profiles with a link to each. Oldest first.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact_method", "description": "The type of this record. Always `contact_method`.", "type": "string", "enum": [ "contact_method" ] }, "id": { "type": "string", "description": "The method. Remove it with `DELETE /contacts/{id}/methods/{methodId}`." }, "kind": { "type": "string", "enum": [ "email", "phone", "fax", "linkedin", "instagram", "facebook", "x", "tiktok" ], "description": "An extra `email`, `phone` or `fax`, or a social profile: `linkedin`, `instagram`, `facebook`, `x`, `tiktok`." }, "value": { "type": "string", "description": "The address, the number, or the profile link or handle, as the broker entered it." }, "url": { "nullable": true, "description": "The link to a social profile, built from `value`. Null for an email, phone or fax.", "type": "string" }, "extension": { "nullable": true, "description": "The extension of a phone or fax number.", "type": "string" }, "label": { "nullable": true, "description": "The broker's word for it, e.g. `work` or `reception`.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "value", "url", "extension", "label", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContactMethod", "summary": "Add an email, phone or social profile to a contact", "description": "Adds an extra email, phone, fax number or social profile. A social profile takes a link or a handle. Adding one the contact already has returns 409.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone", "fax", "linkedin", "instagram", "facebook", "x", "tiktok" ], "description": "What it is. The primary email and phone are fields on the contact, not methods." }, "value": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The address, the number, or the profile link or handle." }, "extension": { "description": "The extension. Only for a phone or fax.", "nullable": true, "type": "string", "maxLength": 16 }, "label": { "description": "Your word for it, e.g. `work`.", "nullable": true, "type": "string", "maxLength": 80 } }, "required": [ "kind", "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_method", "description": "The type of this record. Always `contact_method`.", "type": "string", "enum": [ "contact_method" ] }, "id": { "type": "string", "description": "The method. Remove it with `DELETE /contacts/{id}/methods/{methodId}`." }, "kind": { "type": "string", "enum": [ "email", "phone", "fax", "linkedin", "instagram", "facebook", "x", "tiktok" ], "description": "An extra `email`, `phone` or `fax`, or a social profile: `linkedin`, `instagram`, `facebook`, `x`, `tiktok`." }, "value": { "type": "string", "description": "The address, the number, or the profile link or handle, as the broker entered it." }, "url": { "nullable": true, "description": "The link to a social profile, built from `value`. Null for an email, phone or fax.", "type": "string" }, "extension": { "nullable": true, "description": "The extension of a phone or fax number.", "type": "string" }, "label": { "nullable": true, "description": "The broker's word for it, e.g. `work` or `reception`.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "value", "url", "extension", "label", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The contact already has this email, number or profile (ALREADY_EXISTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/methods/{methodId}": { "delete": { "operationId": "deleteContactMethod", "summary": "Remove an email, phone or social profile from a contact", "description": "Removes one extra email, phone, fax number or social profile. The primary `email` and `phone` are not methods.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "methodId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/relationships": { "get": { "operationId": "listContactRelationships", "summary": "List a contact's relationships", "description": "The people this contact is related to, as the contact page shows them, worded from this contact's side. A relationship to a contact your key cannot read is not listed.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact_relationship", "description": "The type of this record. Always `contact_relationship`.", "type": "string", "enum": [ "contact_relationship" ] }, "id": { "type": "string", "description": "The relationship." }, "type": { "type": "string", "description": "The kind of relationship: spouse, ex_spouse, partner, common_law, parent, child, sibling, grandparent, grandchild, relative, friend, cosigner, guarantor, dependent, business_partner, power_of_attorney, estate_executor, realtor, lawyer, appraiser, accountant, financial_planner, insurance, builder, other." }, "label": { "type": "string", "description": "The relationship worded from this contact's side, e.g. `Spouse of` or `Parent of`." }, "note": { "nullable": true, "description": "The broker's note on the relationship.", "type": "string" }, "contact_id": { "type": "string", "description": "The other contact." }, "contact_name": { "type": "string", "description": "The other contact's name, for display." }, "created_by_user_id": { "nullable": true, "description": "The user who recorded it. Null when that user was removed, or when an import recorded it.", "type": "string" }, "created_at": { "type": "string", "description": "When the broker recorded it." }, "updated_at": { "type": "string", "description": "When the type, label, or note last changed." } }, "required": [ "object", "id", "type", "label", "note", "contact_id", "contact_name", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes": { "get": { "operationId": "listContactNotes", "summary": "List notes on a contact", "description": "Pinned first, then newest - the order a broker sees in BrokerPlus.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContactNote", "summary": "Add a note to a contact", "description": "The note is attributed to the broker your key acts as.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." }, "pinned": { "description": "Defaults to `false`.", "type": "boolean" }, "parent_id": { "description": "Reply to this note. Must belong to the same record, and cannot itself be a reply.", "nullable": true, "type": "string" }, "type": { "description": "The kind of note, as a `slug` from `GET /v1/note-types` for the same scope (deal or contact). Defaults to `general`. A reply always has the kind of its parent, so this is ignored on a reply.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes/{noteId}": { "patch": { "operationId": "updateContactNote", "summary": "Update a note on a contact", "description": "Edit the words, pin or unpin the note, or change its kind. Only the fields you send change. A teammate newly named with a mention gets a notification, as in BrokerPlus.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "description": "The new note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content.", "type": "string", "minLength": 1, "maxLength": 20000 }, "pinned": { "description": "`true` pins the note to the top of the record. A pin does not change `updated_at`.", "type": "boolean" }, "type": { "description": "Change the kind of note, for example `underwriting`. The brokerage must have this kind. A reply always has the kind of its parent, so you cannot change it on a reply.", "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteContactNote", "summary": "Delete a note from a contact", "description": "Deletes the note and its replies. You cannot undo this. Any teammate who can edit the contact can delete its notes, as in BrokerPlus.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes/mentionable": { "get": { "operationId": "listContactNoteMentionables", "summary": "List who a contact note can mention", "description": "The teammates on the contact's team, by name. To mention one in a note, put `@Name` in the body. The teammate gets a notification, as in BrokerPlus. A mention of somebody who is not in this list is kept as text, and nobody gets a notification.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "user", "description": "The type of this record. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "The teammate's user id. Put it in a mention in a note body." }, "name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "object", "id", "name" ], "additionalProperties": false }, "description": "The teammates a contact note can mention." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes/{noteId}/reactions": { "post": { "operationId": "reactContactNote", "summary": "React to a contact note", "description": "Adds or takes off one emoji reaction of the broker your key acts as. Sending the same reaction again changes nothing. A reaction also marks a mention of that broker in the note as seen.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "minLength": 1, "maxLength": 32, "description": "One emoji, for example `👍`." }, "active": { "type": "boolean", "description": "`true` adds the reaction of the broker your key acts as. `false` takes it off." } }, "required": [ "emoji", "active" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`emoji` is not one emoji (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes/{noteId}/attachments": { "post": { "operationId": "attachContactNoteFile", "summary": "Attach a PDF to a contact note", "description": "Send the file as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. The file must be a PDF of at most 25 MB. BrokerPlus checks the content, not the name. The response does not include a link: get one with the file's `id`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "The PDF, at most 25 MB. Its file name is the name that BrokerPlus shows." } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file name that BrokerPlus shows. `.pdf` is added when it is not there." }, "content_base64": { "type": "string", "minLength": 1, "description": "The file, in standard base64. It must be a PDF of at most 25 MB. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing or empty (NO_FILE), is not a PDF (INVALID_TYPE), is larger than 25 MB (FILE_TOO_LARGE), or the base64 is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/notes/{noteId}/attachments/{attachmentId}": { "get": { "operationId": "getContactNoteFile", "summary": "Get a link to a file on a contact note", "description": "A signed link to the PDF, valid for five minutes.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." }, "download_url": { "type": "string", "description": "A link to the file. It carries its own authorization, so do not store it." }, "download_url_expires_at": { "type": "string", "description": "When the link stops working, five minutes after you asked for it." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/drafts": { "post": { "operationId": "createContactDraft", "summary": "File a message for the broker to review", "description": "Writes an `sms` or `email` draft into the review queue of the broker your key acts as. The API never sends it. The broker reads the draft in BrokerPlus, and approves, edits, or rejects it there. Use this endpoint when your own system writes the message and a person must read it before a client does.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "`sms` or `email`." }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The message text. Plain text. An `sms` body over 1600 characters is refused." }, "subject": { "description": "Required for `email`. Not accepted for `sms`.", "type": "string", "minLength": 1, "maxLength": 500 }, "deal_id": { "description": "Link the draft to a deal. The deal must be one that your key can reach.", "type": "string" } }, "required": [ "channel", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/messages": { "post": { "operationId": "sendContactMessage", "summary": "Send a message to a contact", "description": "Sends an `email` or `sms` to this contact now, from the connected mailbox or phone number of the broker your key acts as. Set `send_at` to send it later instead. The message is the broker's own: it is in their drafts folder as `sent` (or `scheduled`), and in Sent. The response is `201` with the draft. Read the sent message with `GET /v1/communications/{id}` and the draft's `communication_id`. An email is sent in the background, so `communication_id` can be null for a short time. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "`sms` or `email`." }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The message text, exactly as the client will read it. Plain text. An `sms` body over 1600 characters is refused." }, "subject": { "description": "Required for `email`. Not accepted for `sms`.", "type": "string", "minLength": 1, "maxLength": 500 }, "deal_id": { "description": "Link the draft to a deal. The deal must be one that your key can reach.", "type": "string" }, "send_at": { "type": "string", "description": "When the message goes out, as an ISO 8601 timestamp in the future. Leave it out to send now. Until then the draft is `scheduled`: move it with `POST /drafts/{id}/schedule`, or stop it with `POST /drafts/{id}/unschedule`." } }, "required": [ "channel", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The brokerage has no connected email inbox (NO_EMAIL_INBOX).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED) or no phone number (SMS_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts": { "get": { "operationId": "listDrafts", "summary": "List filed drafts", "description": "The drafts filed through the API (new messages, replies and forwards) that the broker your key acts as can review, newest first. Use `status` to see which ones were sent, scheduled or discarded. Drafts written in BrokerPlus itself are not listed.", "tags": [ "Contacts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only drafts addressed to this contact." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only drafts about this deal." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ] }, "description": "`pending_review`, `scheduled`, `sent`, `discarded`, or `failed`." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sms", "email" ] }, "description": "`sms` or `email`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts/{id}": { "get": { "operationId": "getDraft", "summary": "Retrieve a filed draft", "description": "One draft filed through the API, with its review status.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDraft", "summary": "Edit a draft", "description": "Changes a draft that waits for review, as the broker does in their drafts folder: the subject, the text, who it goes to, and its files. Send only the fields to change. Nothing goes to the client. Send it afterwards with `POST /drafts/{id}/send`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "description": "The new subject line. Not accepted for a text.", "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The new message text. Plain text. A text over 1600 characters is refused." }, "body_html": { "description": "The new formatted version of an email body, or null to send `body` as written. Send it with `body`, or the two can say different things. Not accepted for a text.", "nullable": true, "type": "string", "maxLength": 200000 }, "to": { "description": "Replaces the addresses the email goes to. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "cc": { "description": "Replaces the copied addresses. Send an empty list to remove them all. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "bcc": { "description": "Replaces the blind-copied addresses. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "attachments": { "description": "Replaces the files the email carries, at most 10. Send an empty list to remove them all. Not accepted for a text.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `rates.pdf`." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, GIF, TIFF, WebP, Word, Excel, PowerPoint, CSV, or plain text." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding, and 25 MB for all the files of one email." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "No field to change, or a field a text does not take (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The draft is no longer waiting for review (DRAFT_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/addresses": { "get": { "operationId": "listContactAddresses", "summary": "List a contact's addresses", "description": "The broker's own addresses for this contact, primary first. Residence history from a mortgage application is not here; read it through the application.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact_address", "description": "The type of this record. Always `contact_address`.", "type": "string", "enum": [ "contact_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "contact_id": { "type": "string", "description": "The contact it belongs to." }, "label": { "nullable": true, "description": "The broker's own word for it, e.g. `Home`, `Work`, `Cottage`. Free text.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_address": { "type": "string", "description": "Street number and name, as one line." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province or territory code, e.g. `ON`. Null when not set or not Canadian.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal or ZIP code, as entered.", "type": "string" }, "country": { "type": "string", "enum": [ "CA", "US", "other" ], "description": "Country. `CA` is Canada, `US` the United States, `other` anything else." }, "is_primary": { "type": "boolean", "description": "Whether this is the contact's main address. Exactly one address is primary." }, "created_at": { "type": "string", "description": "When the address was added." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "label", "unit_number", "street_address", "city", "province", "postal_code", "country", "is_primary", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContactAddress", "summary": "Add an address to a contact", "description": "The first address on a contact becomes primary whatever you send. Send `is_primary: true` on a later one to move the primary; the previous primary is demoted in the same write.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "description": "The broker's own word for it, e.g. `Home`. Free text.", "nullable": true, "type": "string", "maxLength": 60 }, "unit_number": { "description": "Unit or suite.", "nullable": true, "type": "string", "maxLength": 40 }, "street_address": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Street number and name, as one line. Required." }, "city": { "description": "City or town.", "nullable": true, "type": "string", "maxLength": 120 }, "province": { "description": "Two-letter province or territory code, e.g. `ON`. Only Canadian codes are recognized.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "description": "Postal or ZIP code. Stored as sent.", "nullable": true, "type": "string", "maxLength": 20 }, "country": { "description": "Defaults to `CA`.", "type": "string", "enum": [ "CA", "US", "other" ] }, "is_primary": { "description": "Send `true` to make this the primary address. The first address on a contact is primary regardless.", "type": "boolean" } }, "required": [ "street_address" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_address", "description": "The type of this record. Always `contact_address`.", "type": "string", "enum": [ "contact_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "contact_id": { "type": "string", "description": "The contact it belongs to." }, "label": { "nullable": true, "description": "The broker's own word for it, e.g. `Home`, `Work`, `Cottage`. Free text.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_address": { "type": "string", "description": "Street number and name, as one line." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province or territory code, e.g. `ON`. Null when not set or not Canadian.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal or ZIP code, as entered.", "type": "string" }, "country": { "type": "string", "enum": [ "CA", "US", "other" ], "description": "Country. `CA` is Canada, `US` the United States, `other` anything else." }, "is_primary": { "type": "boolean", "description": "Whether this is the contact's main address. Exactly one address is primary." }, "created_at": { "type": "string", "description": "When the address was added." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "label", "unit_number", "street_address", "city", "province", "postal_code", "country", "is_primary", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`province` is not a Canadian province or territory code (INVALID_PROVINCE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/addresses/{addressId}": { "patch": { "operationId": "updateContactAddress", "summary": "Update an address", "description": "Send only the fields to change. `is_primary: false` is ignored: a contact always has one primary, so demote an address by promoting another.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "description": "The broker's own word for it, e.g. `Home`. Free text.", "nullable": true, "type": "string", "maxLength": 60 }, "unit_number": { "description": "Unit or suite.", "nullable": true, "type": "string", "maxLength": 40 }, "street_address": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Street number and name, as one line. Required." }, "city": { "description": "City or town.", "nullable": true, "type": "string", "maxLength": 120 }, "province": { "description": "Two-letter province or territory code, e.g. `ON`. Only Canadian codes are recognized.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "description": "Postal or ZIP code. Stored as sent.", "nullable": true, "type": "string", "maxLength": 20 }, "country": { "description": "Defaults to `CA`.", "type": "string", "enum": [ "CA", "US", "other" ] }, "is_primary": { "description": "Send `true` to make this the primary address. The first address on a contact is primary regardless.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_address", "description": "The type of this record. Always `contact_address`.", "type": "string", "enum": [ "contact_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "contact_id": { "type": "string", "description": "The contact it belongs to." }, "label": { "nullable": true, "description": "The broker's own word for it, e.g. `Home`, `Work`, `Cottage`. Free text.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_address": { "type": "string", "description": "Street number and name, as one line." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province or territory code, e.g. `ON`. Null when not set or not Canadian.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal or ZIP code, as entered.", "type": "string" }, "country": { "type": "string", "enum": [ "CA", "US", "other" ], "description": "Country. `CA` is Canada, `US` the United States, `other` anything else." }, "is_primary": { "type": "boolean", "description": "Whether this is the contact's main address. Exactly one address is primary." }, "created_at": { "type": "string", "description": "When the address was added." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "label", "unit_number", "street_address", "city", "province", "postal_code", "country", "is_primary", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`province` is not a Canadian province or territory code (INVALID_PROVINCE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteContactAddress", "summary": "Remove an address", "description": "If the removed address was primary, the oldest remaining address becomes primary.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/statistics": { "get": { "operationId": "getContactStatistics", "summary": "Read a contact's deal statistics", "description": "How many deals the contact borrowed on, how many funded, the dollars funded, whether they are a repeat client, their referrals, and the last thing that happened with them. Computed on read from the deals your key can see. Each figure names its basis.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The contact." }, "as_of": { "type": "string", "description": "When these figures were computed. They are not cached." }, "timezone": { "type": "string", "description": "The zone that decides which calendar year a date falls in." }, "year": { "type": "string", "description": "The calendar year that `year_to_date` figures cover." }, "deals": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals the contact is a borrower on, in any state." }, "open": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Of those, deals not funded and not closed out." }, "funded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Of those, deals that funded." }, "funded_year_to_date": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Funded deals whose funding date falls in `year`." } }, "required": [ "total", "open", "funded", "funded_year_to_date" ], "additionalProperties": false, "description": "Deal counts. A deal counts once for each borrower on it, so a couple's deal is one deal on each of them." }, "funded_volume": { "type": "number", "description": "Dollars funded across the contact's funded deals. Each deal contributes its commission's funded amount, or its application's loan amount when no commission was recorded." }, "funded_volume_year_to_date": { "type": "number", "description": "The same, for deals funded in `year`." }, "funded_deals_without_amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Funded deals that carry neither a commission amount nor a loan amount. They are in the counts and absent from the volume: the volume is a floor, not a total, while this is above zero." }, "first_funded_at": { "nullable": true, "description": "When the contact's first deal funded.", "type": "string" }, "last_funded_at": { "nullable": true, "description": "When their most recent deal funded.", "type": "string" }, "is_repeat_client": { "type": "boolean", "description": "True once two or more of the contact's deals have funded." }, "referrals": { "type": "object", "properties": { "made": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People this contact sent into the book." }, "funded_made": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Of those, referrals whose deal funded." }, "received": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Times this contact was referred in." } }, "required": [ "made", "funded_made", "received" ], "additionalProperties": false, "description": "Person-to-person referrals recorded in BrokerPlus." }, "last_touch": { "nullable": true, "description": "The most recent thing that happened with this contact, across notes, messages and deal changes. Null when nothing has.", "type": "object", "properties": { "at": { "type": "string", "description": "When." }, "kind": { "type": "string", "enum": [ "note", "inbound_message", "outbound_message", "deal_change" ], "description": "What it was: a note on the contact, a message from or to them, or a change on one of their deals." } }, "required": [ "at", "kind" ], "additionalProperties": false } }, "required": [ "contact_id", "as_of", "timezone", "year", "deals", "funded_volume", "funded_volume_year_to_date", "funded_deals_without_amount", "first_funded_at", "last_funded_at", "is_repeat_client", "referrals", "last_touch" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/communication-preferences": { "get": { "operationId": "getCommunicationPreferences", "summary": "Read a contact's email and SMS consent", "description": "Whether the brokerage may send this person commercial email and SMS, by category, and whether a hard suppression stands. A missing preference is implied consent.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The contact." }, "email": { "type": "object", "properties": { "on_file": { "type": "boolean", "description": "Whether the contact has an email address. Without one there is nothing to record against." }, "suppressed": { "nullable": true, "description": "A hard stop, when one exists: `hard_bounce`, `complaint`, or `manual`. Nothing commercial or transactional goes to a suppressed address.", "type": "string" }, "all_commercial": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "The one switch that stops every commercial message, as CASL requires." }, "marketing": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "Marketing campaigns." }, "equity_reports": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "Equity reports on the client's own property." } }, "required": [ "on_file", "suppressed", "all_commercial", "marketing", "equity_reports" ], "additionalProperties": false, "description": "Email standing by category. A withdrawal on `all_commercial` overrides the others." }, "sms": { "type": "object", "properties": { "on_file": { "type": "boolean", "description": "Whether the contact has a phone number." }, "suppressed": { "nullable": true, "description": "A hard stop, when one exists, e.g. a STOP reply.", "type": "string" }, "all": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "One channel, one switch: sms consent is not split by category." } }, "required": [ "on_file", "suppressed", "all" ], "additionalProperties": false, "description": "SMS standing." } }, "required": [ "contact_id", "email", "sms" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCommunicationPreferences", "summary": "Record a contact's email or SMS consent", "description": "Records an opt-out, clears one, or records express consent from something the client did. Opting in never records express consent on its own. A hard suppression is not changed here.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Where this standing comes from, e.g. `website_form` or `crm_import`. Recorded on the row as `api:`." }, "email": { "description": "Send only the categories to change.", "type": "object", "properties": { "all_commercial": { "description": "The switch that stops every commercial message.", "type": "object", "properties": { "action": { "type": "string", "enum": [ "opt_out", "opt_in", "express" ], "description": "`opt_out` records a withdrawal. `opt_in` clears a withdrawal and never records express consent. `express` records express consent from something the client did; say what in `source`." }, "granted_at": { "description": "With `express`: when the client consented. Defaults to now.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expires_at": { "description": "With `express`: when it lapses. Omit for no expiry.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "action" ], "additionalProperties": false }, "marketing": { "description": "Marketing campaigns.", "type": "object", "properties": { "action": { "type": "string", "enum": [ "opt_out", "opt_in", "express" ], "description": "`opt_out` records a withdrawal. `opt_in` clears a withdrawal and never records express consent. `express` records express consent from something the client did; say what in `source`." }, "granted_at": { "description": "With `express`: when the client consented. Defaults to now.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expires_at": { "description": "With `express`: when it lapses. Omit for no expiry.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "action" ], "additionalProperties": false }, "equity_reports": { "description": "Equity reports on the client's own property.", "type": "object", "properties": { "action": { "type": "string", "enum": [ "opt_out", "opt_in", "express" ], "description": "`opt_out` records a withdrawal. `opt_in` clears a withdrawal and never records express consent. `express` records express consent from something the client did; say what in `source`." }, "granted_at": { "description": "With `express`: when the client consented. Defaults to now.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expires_at": { "description": "With `express`: when it lapses. Omit for no expiry.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "action" ], "additionalProperties": false } }, "additionalProperties": false }, "sms": { "description": "SMS standing to change.", "type": "object", "properties": { "all": { "description": "The one SMS switch.", "type": "object", "properties": { "action": { "type": "string", "enum": [ "opt_out", "opt_in", "express" ], "description": "`opt_out` records a withdrawal. `opt_in` clears a withdrawal and never records express consent. `express` records express consent from something the client did; say what in `source`." }, "granted_at": { "description": "With `express`: when the client consented. Defaults to now.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expires_at": { "description": "With `express`: when it lapses. Omit for no expiry.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "action" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "source" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The contact." }, "email": { "type": "object", "properties": { "on_file": { "type": "boolean", "description": "Whether the contact has an email address. Without one there is nothing to record against." }, "suppressed": { "nullable": true, "description": "A hard stop, when one exists: `hard_bounce`, `complaint`, or `manual`. Nothing commercial or transactional goes to a suppressed address.", "type": "string" }, "all_commercial": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "The one switch that stops every commercial message, as CASL requires." }, "marketing": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "Marketing campaigns." }, "equity_reports": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "Equity reports on the client's own property." } }, "required": [ "on_file", "suppressed", "all_commercial", "marketing", "equity_reports" ], "additionalProperties": false, "description": "Email standing by category. A withdrawal on `all_commercial` overrides the others." }, "sms": { "type": "object", "properties": { "on_file": { "type": "boolean", "description": "Whether the contact has a phone number." }, "suppressed": { "nullable": true, "description": "A hard stop, when one exists, e.g. a STOP reply.", "type": "string" }, "all": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "implied", "express", "withdrawn", "expired" ], "description": "`implied` is the default for a client in the book. `express` was recorded from something the client did. `withdrawn` and `expired` mean do not send." }, "source": { "nullable": true, "description": "What recorded the current standing, e.g. the preference centre, a form, or `api:`.", "type": "string" }, "granted_at": { "nullable": true, "description": "When consent was recorded. Null when nothing is on file.", "type": "string" }, "expires_at": { "nullable": true, "description": "When implied consent lapses under CASL, if a date was recorded.", "type": "string" }, "withdrawn_at": { "nullable": true, "description": "When the client opted out. Null while they have not.", "type": "string" } }, "required": [ "status", "source", "granted_at", "expires_at", "withdrawn_at" ], "additionalProperties": false, "description": "One channel, one switch: sms consent is not split by category." } }, "required": [ "on_file", "suppressed", "all" ], "additionalProperties": false, "description": "SMS standing." } }, "required": [ "contact_id", "email", "sms" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The contact has no email address (NO_EMAIL_ON_FILE) or no phone number (NO_PHONE_ON_FILE) to record against.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/tags": { "get": { "operationId": "listContactTagsOnContact", "summary": "List a contact's tags", "description": "Only the tags currently on this contact. For the full vocabulary see `GET /contact-tags`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "assignContactTag", "summary": "Put a tag on a contact", "description": "Assigning a tag the contact already has is a no-op, not an error. A tag newly put on fires the `contact.tag_assigned` automation trigger.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "string", "description": "A tag id from `GET /contact-tags` or `GET /deal-tags`." } }, "required": [ "tag_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/tags/{tagId}": { "delete": { "operationId": "removeContactTag", "summary": "Take a tag off a contact", "description": "Idempotent - removing a tag that was not there still returns 200.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/partner-roles": { "get": { "operationId": "listContactPartnerRoles", "summary": "List a contact's partner roles", "description": "What the contact does for the broker's clients, for example `realtor` or `lawyer`, with their title, website, booking link and photo. A contact with any role is a partner.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact_partner_role", "description": "The type of this record. Always `contact_partner_role`.", "type": "string", "enum": [ "contact_partner_role" ] }, "id": { "type": "string", "description": "Stable identifier for the role." }, "contact_id": { "type": "string", "description": "The contact who holds the role." }, "role": { "type": "string", "description": "The role, for example `realtor`, `lawyer`, `appraiser`, `lender_contact`, `financial_planner` or `builder`, or a word the brokerage made up itself." }, "role_label": { "type": "string", "description": "The role as BrokerPlus shows it, for example `Lawyer / notary`." }, "title": { "nullable": true, "description": "The person's job title, for example `Sales Representative`.", "type": "string" }, "website": { "nullable": true, "description": "The person's public profile page.", "type": "string" }, "calendar_url": { "nullable": true, "description": "A link where a client can book time with the person.", "type": "string" }, "photo_url": { "nullable": true, "description": "The person's photo, as shown on equity reports. The broker uploads it in BrokerPlus.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "title", "website", "calendar_url", "photo_url" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "addContactPartnerRole", "summary": "Give a contact a partner role", "description": "Adds a role, for example `realtor`, and makes the contact a partner, as the role picker on the contact page does. If the contact already holds the role, the role is kept and its `title` is updated when you send one.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The role, for example `realtor` or `lawyer`. The contact becomes a partner. If the contact already holds the role, it is kept and `title` is updated when you send it." }, "title": { "description": "The person's job title.", "nullable": true, "type": "string", "maxLength": 120 } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_partner_role", "description": "The type of this record. Always `contact_partner_role`.", "type": "string", "enum": [ "contact_partner_role" ] }, "id": { "type": "string", "description": "Stable identifier for the role." }, "contact_id": { "type": "string", "description": "The contact who holds the role." }, "role": { "type": "string", "description": "The role, for example `realtor`, `lawyer`, `appraiser`, `lender_contact`, `financial_planner` or `builder`, or a word the brokerage made up itself." }, "role_label": { "type": "string", "description": "The role as BrokerPlus shows it, for example `Lawyer / notary`." }, "title": { "nullable": true, "description": "The person's job title, for example `Sales Representative`.", "type": "string" }, "website": { "nullable": true, "description": "The person's public profile page.", "type": "string" }, "calendar_url": { "nullable": true, "description": "A link where a client can book time with the person.", "type": "string" }, "photo_url": { "nullable": true, "description": "The person's photo, as shown on equity reports. The broker uploads it in BrokerPlus.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "title", "website", "calendar_url", "photo_url" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/partner-roles/{roleId}": { "patch": { "operationId": "updateContactPartnerRole", "summary": "Update a partner role", "description": "Changes the title, website or booking link on one of the contact's roles. Only the fields you send change. The photo is uploaded in BrokerPlus.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "The job title. `null` clears it.", "nullable": true, "type": "string", "maxLength": 120 }, "website": { "description": "The public profile page. `null` clears it.", "nullable": true, "type": "string", "maxLength": 500, "format": "uri" }, "calendar_url": { "description": "The booking link. `null` clears it.", "nullable": true, "type": "string", "maxLength": 500, "format": "uri" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_partner_role", "description": "The type of this record. Always `contact_partner_role`.", "type": "string", "enum": [ "contact_partner_role" ] }, "id": { "type": "string", "description": "Stable identifier for the role." }, "contact_id": { "type": "string", "description": "The contact who holds the role." }, "role": { "type": "string", "description": "The role, for example `realtor`, `lawyer`, `appraiser`, `lender_contact`, `financial_planner` or `builder`, or a word the brokerage made up itself." }, "role_label": { "type": "string", "description": "The role as BrokerPlus shows it, for example `Lawyer / notary`." }, "title": { "nullable": true, "description": "The person's job title, for example `Sales Representative`.", "type": "string" }, "website": { "nullable": true, "description": "The person's public profile page.", "type": "string" }, "calendar_url": { "nullable": true, "description": "A link where a client can book time with the person.", "type": "string" }, "photo_url": { "nullable": true, "description": "The person's photo, as shown on equity reports. The broker uploads it in BrokerPlus.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "title", "website", "calendar_url", "photo_url" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact or the role does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "removeContactPartnerRole", "summary": "Take a partner role off a contact", "description": "Removes the role. When the contact's last role goes, the contact is no longer a partner. The contact itself stays in the book.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact or the role does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contact-tags": { "get": { "operationId": "listContactTags", "summary": "List contact tags", "description": "The brokerage's contact tag vocabulary. Deal tags are a separate list.", "tags": [ "Tags" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContactTag", "summary": "Create a contact tag", "description": "Adds a tag to the brokerage's contact tag list, the same as Settings in BrokerPlus. The new tag goes to the end of the order. A name that an archived tag had restores that tag. A contact tag with `is_type` true is one of the brokerage's contact types.", "tags": [ "Tags" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." }, "is_type": { "type": "boolean", "description": "Contact tags only. True files the tag as one of the brokerage's contact types, in the Type row of a contact. It assigns and filters like any other tag. Defaults to false. A deal tag refuses this field." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The name is empty or longer than 40 characters, or the colour is not in the palette (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live contact tag has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contact-tags/{id}": { "patch": { "operationId": "updateContactTag", "summary": "Update a contact tag", "description": "Changes the name or colour of a contact tag. It also moves the tag into or out of the Type row with `is_type`. Every contacts that has the tag keeps it.", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." }, "is_type": { "type": "boolean", "description": "Contact tags only. True files the tag as one of the brokerage's contact types, in the Type row of a contact. It assigns and filters like any other tag. Defaults to false. A deal tag refuses this field." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live contact tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another live contact tag has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveContactTag", "summary": "Archive a contact tag", "description": "Removes the tag from the list and from every contact that has it, the same as Delete in Settings. To restore the name, create a tag with the same name. The contacts do not get the tag back.", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live contact tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deal-tags": { "get": { "operationId": "listDealTags", "summary": "List deal tags", "description": "The brokerage's deal tag vocabulary. A deal tag cannot be put on a contact.", "tags": [ "Tags" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealTag", "summary": "Create a deal tag", "description": "Adds a tag to the brokerage's deal tag list, the same as Settings in BrokerPlus. The new tag goes to the end of the order. A name that an archived tag had restores that tag.", "tags": [ "Tags" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." }, "is_type": { "type": "boolean", "description": "Contact tags only. True files the tag as one of the brokerage's contact types, in the Type row of a contact. It assigns and filters like any other tag. Defaults to false. A deal tag refuses this field." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The name is empty or longer than 40 characters, or the colour is not in the palette (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live deal tag has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deal-tags/{id}": { "patch": { "operationId": "updateDealTag", "summary": "Update a deal tag", "description": "Changes the name or colour of a deal tag. Every deals that has the tag keeps it.", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." }, "is_type": { "type": "boolean", "description": "Contact tags only. True files the tag as one of the brokerage's contact types, in the Type row of a contact. It assigns and filters like any other tag. Defaults to false. A deal tag refuses this field." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live deal tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another live deal tag has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveDealTag", "summary": "Archive a deal tag", "description": "Removes the tag from the list and from every deal that has it, the same as Delete in Settings. To restore the name, create a tag with the same name. The deals do not get the tag back.", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live deal tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads": { "get": { "operationId": "listLeads", "summary": "List leads", "description": "Inbound prospects, before they become deals. Archived and converted leads are included unless you exclude them. To find the lead for a person, send `email` or `phone`.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Send `false` to exclude archived and converted leads." }, { "name": "lead_form_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the leads that this lead form brought in. Find the id with `GET /v1/lead-forms`." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Exact email address. Case and surrounding spaces are ignored. Matches the contact's main email or any additional email. No match returns an empty list, not 404." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Phone number in any format. Matches on the last 10 digits, so `+1 (587) 555-1234` and `5875551234` find the same contact. Matches the main phone or any additional phone." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text search over the name, nickname, company, email and phone. Every word must match part of one of them. The same search as the search bar in BrokerPlus." }, { "name": "custom_field", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Filter by a contact custom field: `custom_field[]=`, for example `custom_field[lead_source]=Google`. The value takes the same text as a write. An empty value finds records with no answer. Send up to 10; a record must match all of them. Get the keys from `GET /v1/custom-fields?entity=contact`.", "style": "deepObject", "explode": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "A `phone` with no digits, a `custom_field` key the brokerage does not have, or a value that does not fit the field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createLead", "summary": "Create a lead", "description": "Creates the contact and the lead together, exactly as the in-app Add Lead does. This is the endpoint to point your own website form at. Send `custom_fields` to set the person's custom fields in the same call.", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Given name. The only required field." }, "last_name": { "description": "Family name.", "nullable": true, "type": "string", "maxLength": 200 }, "email": { "description": "Must be a valid address if provided.", "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "Stored as sent. Any format is accepted.", "nullable": true, "type": "string", "maxLength": 40 }, "service_type": { "description": "What they are asking for, in your own words.", "nullable": true, "type": "string", "maxLength": 120 }, "first_time_buyer": { "description": "Defaults to `false`.", "type": "boolean" }, "next_follow_up_at": { "description": "ISO 8601 timestamp. When to follow up next.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "additional_details": { "description": "Free-text notes to attach to the lead.", "nullable": true, "type": "string", "maxLength": 5000 }, "custom_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values by `key`, e.g. `{\"lead_source\": \"Google\", \"click_id\": \"abc123\"}`. A lead's custom fields are its contact's fields; list the keys with `GET /v1/custom-fields?entity=contact`. Each value takes the same text as `PATCH /v1/contacts/{id}/custom-fields/{key}`. One bad key or value refuses the whole request, and `details` names each one." } }, "required": [ "first_name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid, or a `custom_fields` key or value is wrong. Nothing is created. `details.custom_fields` names each bad key (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}": { "get": { "operationId": "getLead", "summary": "Retrieve a lead", "description": "A single lead by id, including the raw capture metadata it arrived with.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateLead", "summary": "Update a lead", "description": "Changes the fields a broker edits on the Leads board, and the person's custom fields. Only the fields you send are changed. The name, email and phone belong to the contact: change them with `PATCH /v1/contacts/{id}`.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "nullable": true, "description": "A stage from `GET /v1/lead-stages`. Send `null` to clear it.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, in your own words.", "type": "string", "maxLength": 120 }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower is a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "ISO 8601 timestamp. When to follow up next.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "additional_details": { "nullable": true, "description": "Free-text notes on the lead.", "type": "string", "maxLength": 5000 }, "referral_source_id": { "nullable": true, "description": "A referral partner from `GET /v1/referral-sources`. The deal behind the lead gets it too.", "type": "string" }, "channel_id": { "nullable": true, "description": "A channel from `GET /v1/lead-channels`. The deal behind the lead gets it too.", "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values by `key`, e.g. `{\"lead_source\": \"Google\", \"click_id\": \"abc123\"}`. A lead's custom fields are its contact's fields; list the keys with `GET /v1/custom-fields?entity=contact`. Each value takes the same text as `PATCH /v1/contacts/{id}/custom-fields/{key}`. One bad key or value refuses the whole request, and `details` names each one." } }, "additionalProperties": false, "description": "Send only the fields to change. To archive or convert a lead, use its action endpoints." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "An id that is not in its list, or a bad `custom_fields` key or value. `details` names the field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "You sent `custom_fields`, and the lead's contact belongs to another team (CONTACT_NOT_WRITABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}/archive": { "post": { "operationId": "archiveLead", "summary": "Archive a lead", "description": "Takes the lead out of the funnel without a deal, as Archive does in BrokerPlus. Archiving an archived lead changes nothing.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}/unarchive": { "post": { "operationId": "unarchiveLead", "summary": "Unarchive a lead", "description": "Puts an archived lead back in the funnel. Unarchiving an open lead changes nothing.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The lead became a deal (LEAD_CONVERTED), or the person already has another open lead, named in `details.open_lead_id` (LEAD_ALREADY_OPEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}/convert": { "post": { "operationId": "convertLead", "summary": "Convert a lead to a deal", "description": "Starts a deal from the lead, as Create Deal does in BrokerPlus. The lead becomes `converted` and `converted_deal_id` is the new deal. Converting a converted lead changes nothing and returns the same deal.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Deal type. Defaults to `purchase`. Decides which pipeline the deal lands on when you do not name one.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "board_id": { "description": "Pipeline to land on, from `GET /v1/pipelines`. Omit to use the broker's pipeline for the type.", "nullable": true, "type": "string" }, "stage_id": { "description": "Stage within `board_id`. Omit to land on the pipeline's first stage. Requires `board_id`.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead", "description": "The type of this record. Always `lead`.", "type": "string", "enum": [ "lead" ] }, "id": { "type": "string", "description": "Stable identifier for the lead." }, "contact_id": { "nullable": true, "description": "The contact created from this lead. Null until one is linked.", "type": "string" }, "first_name": { "nullable": true, "description": "The person's given name, read from the lead's contact. A change to the name changes the contact's `updated_at`, not the lead's.", "type": "string" }, "last_name": { "nullable": true, "description": "The person's family name, read from the lead's contact.", "type": "string" }, "email": { "nullable": true, "description": "The person's email address, read from the lead's contact.", "type": "string" }, "phone": { "nullable": true, "description": "The person's phone number, read from the lead's contact.", "type": "string" }, "source": { "type": "string", "enum": [ "form", "calculator", "manual", "voice", "telephony", "import", "inbound_email", "portal", "api", "booking", "meeting", "assistant" ], "description": "How the lead reached the brokerage. `portal` is a person who opened a shared client link. `api` is a lead you sent with `POST /v1/leads`. `booking` is a person who booked a meeting through one of the broker's booking links." }, "status": { "type": "string", "enum": [ "open", "archived", "converted" ], "description": "`open` is a lead in the funnel. `converted` is a lead that became a deal; the deal is `converted_deal_id`. `archived` is a lead the broker took out of the funnel without a deal." }, "converted_deal_id": { "nullable": true, "description": "The deal this lead became. Null until the lead is converted. Read it with `GET /v1/deals/{id}`.", "type": "string" }, "stage_id": { "nullable": true, "description": "The lead's stage on the Leads board. Null before the lead is triaged. List the stages with `GET /v1/lead-stages`.", "type": "string" }, "stage_name": { "nullable": true, "description": "The name of `stage_id`, as the broker sees it.", "type": "string" }, "referral_source_id": { "nullable": true, "description": "The referral partner the broker tagged. List them with `GET /v1/referral-sources`.", "type": "string" }, "referral_source_name": { "nullable": true, "description": "The name of `referral_source_id`.", "type": "string" }, "channel_id": { "nullable": true, "description": "How the lead found the brokerage, e.g. Google or a referral. List them with `GET /v1/lead-channels`.", "type": "string" }, "channel_name": { "nullable": true, "description": "The name of `channel_id`.", "type": "string" }, "lead_form_id": { "nullable": true, "description": "The website form the person filled in. Null for a lead that did not come through a form, or whose form was deleted.", "type": "string" }, "lead_form_name": { "nullable": true, "description": "The name of `lead_form_id`.", "type": "string" }, "service_type": { "nullable": true, "description": "What they are asking for, e.g. a purchase or a renewal.", "type": "string" }, "first_time_buyer": { "type": "boolean", "description": "Whether the borrower declared themselves a first-time buyer." }, "next_follow_up_at": { "nullable": true, "description": "When the broker intends to follow up next.", "type": "string" }, "additional_details": { "nullable": true, "description": "Free-text notes captured with the lead.", "type": "string" }, "archived_at": { "nullable": true, "description": "Set when the lead graduates into a deal or is archived by hand.", "type": "string" }, "submission_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times this person has submitted. Repeats do not create new leads." }, "submission": { "type": "object", "additionalProperties": {}, "description": "Unstructured capture metadata. Shape is NOT guaranteed." }, "created_at": { "type": "string", "description": "When the lead was captured." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "contact_id", "first_name", "last_name", "email", "phone", "source", "status", "converted_deal_id", "stage_id", "stage_name", "referral_source_id", "referral_source_name", "channel_id", "channel_name", "lead_form_id", "lead_form_name", "service_type", "first_time_buyer", "next_follow_up_at", "additional_details", "archived_at", "submission_count", "submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`board_id` or `stage_id` is not one of the broker's pipelines or stages (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The lead has no contact or its deal was deleted (LEAD_NOT_CONVERTIBLE), or the broker has no pipeline for the deal type (BROKER_HAS_NO_BOARDS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}/custom-fields": { "get": { "operationId": "listLeadCustomFields", "summary": "List a lead's custom fields", "description": "The custom fields of the lead's contact, with their values. A lead's custom fields are its contact's fields, so this is the same list as `GET /v1/contacts/{contact_id}/custom-fields`.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/{id}/custom-fields/{key}": { "patch": { "operationId": "setLeadCustomField", "summary": "Set a custom field on a lead", "description": "Sets one of the lead's contact fields by its `key`. Send an empty string to clear it. To set several at once, send `custom_fields` to `PATCH /v1/leads/{id}`.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to store, as text. A `short_text` field takes one line of 200 characters or fewer, and line breaks change to spaces. A `number`,`money` or `percent` field takes a number like `1200` or `4.5`, a `date` field takes `YYYY-MM-DD`, a `checkbox` takes `true` or `false`, a `url` takes a full web address, a `select` field takes one of its options, and a `multi_select` field takes a JSON array of its options, like `[\"Appraisal\",\"Insurance\"]`. Send an empty string to clear the field." } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The value does not fit the field's type or its options (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The lead has no contact, or no live contact field has that `key` (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-stages": { "get": { "operationId": "listLeadStages", "summary": "List lead stages", "description": "The columns of the brokerage's Leads board, in order. Send one as `stage_id` on a lead.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createLeadStage", "summary": "Create a lead stage", "description": "Adds a column to the end of the Leads board, the same as the board settings in BrokerPlus. A name that a deleted stage had restores that stage.", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "What the brokerage calls it, 40 characters or fewer. It must be unique among the live ones." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live lead stage has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-stages/reorder": { "post": { "operationId": "reorderLeadStages", "summary": "Put lead stages in order", "description": "Sets the column order of the Leads board. Send the stage ids first to last. Returns the stages in the new order.", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "Lead stage ids in the new board order, first to last. Each id must be a live stage of your brokerage, or nothing changes." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "An id is not a live lead stage of your brokerage, and the order did not change (UNKNOWN_STAGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-stages/{id}": { "patch": { "operationId": "updateLeadStage", "summary": "Rename a lead stage", "description": "Changes the name of a column on the Leads board. The leads in the stage stay in it.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "What the brokerage calls it, 40 characters or fewer. It must be unique among the live ones." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live lead stage in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another live lead stage has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteLeadStage", "summary": "Delete a lead stage", "description": "Removes a column from the Leads board, the same as Delete in BrokerPlus. The leads in the stage move to `move_to`, or to the first stage that stays when you omit it. The board must keep one stage.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "move_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The lead stage that gets the leads of the deleted stage. Defaults to the first stage that stays." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`move_to` is not a live lead stage of your brokerage, or it is the stage you delete (INVALID_DESTINATION).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live lead stage in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "This is the last stage on the board (LAST_STAGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/referral-sources": { "get": { "operationId": "listReferralSources", "summary": "List referral sources", "description": "The referral partners the brokerage tags leads with. Send one as `referral_source_id` on a lead.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "referral_source", "description": "The type of this record. Always `referral_source`.", "type": "string", "enum": [ "referral_source" ] }, "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." }, "type": { "nullable": true, "description": "What kind of partner this is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" }, "company": { "nullable": true, "description": "The firm the partner works for, e.g. a realty brokerage or a law practice.", "type": "string" }, "contact_id": { "nullable": true, "description": "The partner as a contact in the brokerage's book. Resolve against `GET /contacts/{id}`. The partner's figures are on `GET /referral-partners/{id}`.", "type": "string" }, "contact_details": { "nullable": true, "description": "How to reach the partner, in the broker's own words, e.g. a phone number and an assistant's name.", "type": "string" }, "notes": { "nullable": true, "description": "The broker's notes on the relationship.", "type": "string" }, "last_contact_at": { "nullable": true, "description": "When the broker last recorded being in touch with the partner. `GET /referral-partners` reads the last message instead.", "type": "string" }, "next_follow_up_at": { "nullable": true, "description": "When the broker means to get back in touch.", "type": "string" } }, "required": [ "object", "id", "name", "position", "type", "company", "contact_id", "contact_details", "notes", "last_contact_at", "next_follow_up_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createReferralSource", "summary": "Create a referral partner", "description": "Adds a referral partner, the same as Add Partner on the Partners page. A referral partner is a referral source with a contact behind it. Send `contact_id` to use a contact you have. Omit it, and BrokerPlus makes a partner contact from the name and the details you send. The new partner goes to the end of the order.", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The partner's name, 120 characters or fewer. It must be unique among the live partners." }, "contact_id": { "description": "A contact in your brokerage to use as the partner. Omit it, and BrokerPlus makes a partner contact from `name`, `first_name`, `last_name`, `email`, and `phone`.", "nullable": true, "type": "string" }, "first_name": { "description": "The first name of the new partner contact. Ignored when you send `contact_id`.", "nullable": true, "type": "string", "maxLength": 80 }, "last_name": { "description": "The last name of the new partner contact. Ignored when you send `contact_id`.", "nullable": true, "type": "string", "maxLength": 80 }, "email": { "description": "The email address of the new partner contact. Ignored when you send `contact_id`.", "nullable": true, "type": "string", "maxLength": 200 }, "phone": { "description": "The phone number of the new partner contact. Ignored when you send `contact_id`.", "nullable": true, "type": "string", "maxLength": 40 }, "type": { "description": "What kind of partner this is, for example `realtor` or `lawyer`. BrokerPlus stores a known kind in its usual spelling.", "nullable": true, "type": "string", "maxLength": 80 }, "company": { "description": "The firm the partner works for. When another partner has the same firm with different capital letters, BrokerPlus uses that spelling.", "nullable": true, "type": "string", "maxLength": 80 }, "contact_details": { "description": "How to reach the partner, in the broker's own words. An email address or a phone number here also goes on the partner's contact.", "nullable": true, "type": "string", "maxLength": 500 }, "notes": { "description": "The broker's notes on the relationship.", "nullable": true, "type": "string", "maxLength": 2000 }, "last_contact_at": { "description": "ISO 8601 timestamp. When the broker was last in touch with the partner.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "next_follow_up_at": { "description": "ISO 8601 timestamp. When the broker means to get back in touch.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "referral_source", "description": "The type of this record. Always `referral_source`.", "type": "string", "enum": [ "referral_source" ] }, "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." }, "type": { "nullable": true, "description": "What kind of partner this is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" }, "company": { "nullable": true, "description": "The firm the partner works for, e.g. a realty brokerage or a law practice.", "type": "string" }, "contact_id": { "nullable": true, "description": "The partner as a contact in the brokerage's book. Resolve against `GET /contacts/{id}`. The partner's figures are on `GET /referral-partners/{id}`.", "type": "string" }, "contact_details": { "nullable": true, "description": "How to reach the partner, in the broker's own words, e.g. a phone number and an assistant's name.", "type": "string" }, "notes": { "nullable": true, "description": "The broker's notes on the relationship.", "type": "string" }, "last_contact_at": { "nullable": true, "description": "When the broker last recorded being in touch with the partner. `GET /referral-partners` reads the last message instead.", "type": "string" }, "next_follow_up_at": { "nullable": true, "description": "When the broker means to get back in touch.", "type": "string" } }, "required": [ "object", "id", "name", "position", "type", "company", "contact_id", "contact_details", "notes", "last_contact_at", "next_follow_up_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "`contact_id` is not a contact in your brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live referral partner has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/referral-sources/{id}": { "patch": { "operationId": "updateReferralSource", "summary": "Update a referral partner", "description": "Changes the details of a referral partner. A new name, company, or email address or phone number in `contact_details` also goes on the partner's contact. Send null or an empty string to clear a field.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A new name for the partner. The partner's contact gets the same name.", "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "description": "What kind of partner this is, for example `realtor` or `lawyer`. BrokerPlus stores a known kind in its usual spelling.", "nullable": true, "type": "string", "maxLength": 80 }, "company": { "description": "The firm the partner works for. When another partner has the same firm with different capital letters, BrokerPlus uses that spelling.", "nullable": true, "type": "string", "maxLength": 80 }, "contact_details": { "description": "How to reach the partner, in the broker's own words. An email address or a phone number here also goes on the partner's contact.", "nullable": true, "type": "string", "maxLength": 500 }, "notes": { "description": "The broker's notes on the relationship.", "nullable": true, "type": "string", "maxLength": 2000 }, "last_contact_at": { "description": "ISO 8601 timestamp. When the broker was last in touch with the partner.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "next_follow_up_at": { "description": "ISO 8601 timestamp. When the broker means to get back in touch.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "referral_source", "description": "The type of this record. Always `referral_source`.", "type": "string", "enum": [ "referral_source" ] }, "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." }, "type": { "nullable": true, "description": "What kind of partner this is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" }, "company": { "nullable": true, "description": "The firm the partner works for, e.g. a realty brokerage or a law practice.", "type": "string" }, "contact_id": { "nullable": true, "description": "The partner as a contact in the brokerage's book. Resolve against `GET /contacts/{id}`. The partner's figures are on `GET /referral-partners/{id}`.", "type": "string" }, "contact_details": { "nullable": true, "description": "How to reach the partner, in the broker's own words, e.g. a phone number and an assistant's name.", "type": "string" }, "notes": { "nullable": true, "description": "The broker's notes on the relationship.", "type": "string" }, "last_contact_at": { "nullable": true, "description": "When the broker last recorded being in touch with the partner. `GET /referral-partners` reads the last message instead.", "type": "string" }, "next_follow_up_at": { "nullable": true, "description": "When the broker means to get back in touch.", "type": "string" } }, "required": [ "object", "id", "name", "position", "type", "company", "contact_id", "contact_details", "notes", "last_contact_at", "next_follow_up_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The change also edits the partner's contact, and that contact's broker locked its details (CLIENT_DATA_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live referral partner in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another live referral partner has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveReferralSource", "summary": "Archive a referral partner", "description": "Removes the partner from the list, the same as Delete on the Partners page. The leads that named the partner as their referral source then have no referral source. The partner's contact stays in the book.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live referral partner in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-channels": { "get": { "operationId": "listLeadChannels", "summary": "List lead channels", "description": "How leads find the brokerage, e.g. Google or a referral. Send one as `channel_id` on a lead.", "tags": [ "Leads" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createLeadChannel", "summary": "Create a lead channel", "description": "Adds a channel to the end of the brokerage's list, the same as the channel settings in BrokerPlus.", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "What the brokerage calls it, 40 characters or fewer. It must be unique among the live ones." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live lead channel has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-channels/{id}": { "patch": { "operationId": "updateLeadChannel", "summary": "Update a lead channel", "description": "Renames a channel, or moves it in the order. You cannot rename a channel that BrokerPlus made for every brokerage.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A new name, 40 characters or fewer. You cannot rename a channel that BrokerPlus made for every brokerage, because the funnel report compares brokerages on these names.", "type": "string", "minLength": 1, "maxLength": 40 }, "position": { "description": "The channel's place in the brokerage's own order, lowest first.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier. Send it as the matching `_id` field on a lead." }, "name": { "type": "string", "description": "What the brokerage calls it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Its place in the brokerage's own order, lowest first." } }, "required": [ "id", "name", "position" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing (VALIDATION_ERROR), or the channel is one that BrokerPlus made (SYSTEM_CHANNEL).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live lead channel in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another live lead channel has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveLeadChannel", "summary": "Archive a lead channel", "description": "Removes the channel from the list. The leads and deals that had the channel then have no channel, and the funnel report stops counting it.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live lead channel in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-forms": { "get": { "operationId": "listLeadForms", "summary": "List lead forms", "description": "The forms the broker puts on a website to capture leads, newest first, with how many leads each one brought in. List a form's leads with `GET /v1/leads?lead_form_id=`.", "tags": [ "Lead forms" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "lead_form", "description": "The type of this record. Always `lead_form`.", "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "description": "Stable identifier for the lead form." }, "name": { "type": "string", "description": "The name the broker gave the form. Leads show it as `lead_form_name`." }, "slug": { "type": "string", "description": "The form's part of `url`. Unique across BrokerPlus." }, "url": { "type": "string", "description": "The page where somebody fills in the form. Put it in an `iframe` on a website, or link to it. It shows nothing while `enabled` is false." }, "enabled": { "type": "boolean", "description": "True while the form takes answers. False hides the form and keeps its leads." }, "owner_user_id": { "type": "string", "description": "The broker who owns the form. Its leads go to this broker unless `routing` says another." }, "owner_name": { "nullable": true, "description": "The name of `owner_user_id`.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The whole form, as the form builder in BrokerPlus saves it: `headline`, `blurb`, `submitLabel`, `steps`, `questions` (each with `key`, `label`, `type`, `required`, `crm`, `options`, `step`, and `cond`), `thanks` (the thank-you screen and the auto-reply), `routing`, `tagging`, `spam`, `embed`, `subscribe`, and `savings`. Keys are camelCase here, because this is the builder's own format. Every form must ask everyone for a first name and an email." }, "lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every lead the form brought in. List them with `GET /v1/leads?lead_form_id=`." }, "recent_lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads the form brought in during the last 30 days." }, "converted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads from the form that left the Leads board (`archived_at` is set), the same number the Lead Forms screen shows as converted." }, "newest_lead_at": { "nullable": true, "description": "When the form last brought in a lead. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the form was made." }, "updated_at": { "type": "string", "description": "Last change to the form." } }, "required": [ "object", "id", "name", "slug", "url", "enabled", "owner_user_id", "owner_name", "config", "lead_count", "recent_lead_count", "converted_count", "newest_lead_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createLeadForm", "summary": "Create a lead form", "description": "Makes a lead form that the broker owns, through the same checks as the form builder. It takes answers at `url` at once. Leave out `config` for the starter form, which asks for a name and an email. The auto-reply starts off: turn it on with `POST /v1/lead-forms/{id}/turn-on-auto-reply`.", "tags": [ "Lead forms" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The form's name, 120 characters or fewer." }, "slug": { "description": "The form's part of the page address. BrokerPlus makes it lowercase with hyphens, and adds a short suffix when another form has it. Made from `name` when you leave it out.", "type": "string", "minLength": 3, "maxLength": 60 }, "config": { "description": "The whole form, in the format of `config` on a lead form. Leave it out for the starter form, which asks for a name and an email. The auto-reply must be off (`thanks.autoReply` false): turn it on with `POST /v1/lead-forms/{id}/turn-on-auto-reply`.", "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead_form", "description": "The type of this record. Always `lead_form`.", "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "description": "Stable identifier for the lead form." }, "name": { "type": "string", "description": "The name the broker gave the form. Leads show it as `lead_form_name`." }, "slug": { "type": "string", "description": "The form's part of `url`. Unique across BrokerPlus." }, "url": { "type": "string", "description": "The page where somebody fills in the form. Put it in an `iframe` on a website, or link to it. It shows nothing while `enabled` is false." }, "enabled": { "type": "boolean", "description": "True while the form takes answers. False hides the form and keeps its leads." }, "owner_user_id": { "type": "string", "description": "The broker who owns the form. Its leads go to this broker unless `routing` says another." }, "owner_name": { "nullable": true, "description": "The name of `owner_user_id`.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The whole form, as the form builder in BrokerPlus saves it: `headline`, `blurb`, `submitLabel`, `steps`, `questions` (each with `key`, `label`, `type`, `required`, `crm`, `options`, `step`, and `cond`), `thanks` (the thank-you screen and the auto-reply), `routing`, `tagging`, `spam`, `embed`, `subscribe`, and `savings`. Keys are camelCase here, because this is the builder's own format. Every form must ask everyone for a first name and an email." }, "lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every lead the form brought in. List them with `GET /v1/leads?lead_form_id=`." }, "recent_lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads the form brought in during the last 30 days." }, "converted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads from the form that left the Leads board (`archived_at` is set), the same number the Lead Forms screen shows as converted." }, "newest_lead_at": { "nullable": true, "description": "When the form last brought in a lead. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the form was made." }, "updated_at": { "type": "string", "description": "Last change to the form." } }, "required": [ "object", "id", "name", "slug", "url", "enabled", "owner_user_id", "owner_name", "config", "lead_count", "recent_lead_count", "converted_count", "newest_lead_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `config` field is not valid, or `config` turns the auto-reply on. `details` names each field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-forms/{id}": { "get": { "operationId": "getLeadForm", "summary": "Retrieve a lead form", "description": "One lead form, with the whole form in `config` and its page in `url`.", "tags": [ "Lead forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead_form", "description": "The type of this record. Always `lead_form`.", "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "description": "Stable identifier for the lead form." }, "name": { "type": "string", "description": "The name the broker gave the form. Leads show it as `lead_form_name`." }, "slug": { "type": "string", "description": "The form's part of `url`. Unique across BrokerPlus." }, "url": { "type": "string", "description": "The page where somebody fills in the form. Put it in an `iframe` on a website, or link to it. It shows nothing while `enabled` is false." }, "enabled": { "type": "boolean", "description": "True while the form takes answers. False hides the form and keeps its leads." }, "owner_user_id": { "type": "string", "description": "The broker who owns the form. Its leads go to this broker unless `routing` says another." }, "owner_name": { "nullable": true, "description": "The name of `owner_user_id`.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The whole form, as the form builder in BrokerPlus saves it: `headline`, `blurb`, `submitLabel`, `steps`, `questions` (each with `key`, `label`, `type`, `required`, `crm`, `options`, `step`, and `cond`), `thanks` (the thank-you screen and the auto-reply), `routing`, `tagging`, `spam`, `embed`, `subscribe`, and `savings`. Keys are camelCase here, because this is the builder's own format. Every form must ask everyone for a first name and an email." }, "lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every lead the form brought in. List them with `GET /v1/leads?lead_form_id=`." }, "recent_lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads the form brought in during the last 30 days." }, "converted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads from the form that left the Leads board (`archived_at` is set), the same number the Lead Forms screen shows as converted." }, "newest_lead_at": { "nullable": true, "description": "When the form last brought in a lead. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the form was made." }, "updated_at": { "type": "string", "description": "Last change to the form." } }, "required": [ "object", "id", "name", "slug", "url", "enabled", "owner_user_id", "owner_name", "config", "lead_count", "recent_lead_count", "converted_count", "newest_lead_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateLeadForm", "summary": "Update a lead form", "description": "Renames a lead form, turns it on or off, or replaces the whole form with `config`. A form that is off shows nothing at `url`, and its leads stay in the book. You can turn the auto-reply off here, but you cannot turn it on or change what it says while it is on.", "tags": [ "Lead forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A new name, 120 characters or fewer.", "type": "string", "minLength": 1, "maxLength": 120 }, "enabled": { "description": "False hides the form from its page. Its leads stay in the book.", "type": "boolean" }, "config": { "description": "The whole form. It replaces the form you have, so read `config` first and send it back with your changes. You can turn the auto-reply off here, but not on. While it is on, you cannot change its words or channel.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead_form", "description": "The type of this record. Always `lead_form`.", "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "description": "Stable identifier for the lead form." }, "name": { "type": "string", "description": "The name the broker gave the form. Leads show it as `lead_form_name`." }, "slug": { "type": "string", "description": "The form's part of `url`. Unique across BrokerPlus." }, "url": { "type": "string", "description": "The page where somebody fills in the form. Put it in an `iframe` on a website, or link to it. It shows nothing while `enabled` is false." }, "enabled": { "type": "boolean", "description": "True while the form takes answers. False hides the form and keeps its leads." }, "owner_user_id": { "type": "string", "description": "The broker who owns the form. Its leads go to this broker unless `routing` says another." }, "owner_name": { "nullable": true, "description": "The name of `owner_user_id`.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The whole form, as the form builder in BrokerPlus saves it: `headline`, `blurb`, `submitLabel`, `steps`, `questions` (each with `key`, `label`, `type`, `required`, `crm`, `options`, `step`, and `cond`), `thanks` (the thank-you screen and the auto-reply), `routing`, `tagging`, `spam`, `embed`, `subscribe`, and `savings`. Keys are camelCase here, because this is the builder's own format. Every form must ask everyone for a first name and an email." }, "lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every lead the form brought in. List them with `GET /v1/leads?lead_form_id=`." }, "recent_lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads the form brought in during the last 30 days." }, "converted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads from the form that left the Leads board (`archived_at` is set), the same number the Lead Forms screen shows as converted." }, "newest_lead_at": { "nullable": true, "description": "When the form last brought in a lead. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the form was made." }, "updated_at": { "type": "string", "description": "Last change to the form." } }, "required": [ "object", "id", "name", "slug", "url", "enabled", "owner_user_id", "owner_name", "config", "lead_count", "recent_lead_count", "converted_count", "newest_lead_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `config` field is not valid, or the change turns the auto-reply on or changes it while it is on. `details` names each field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The form does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteLeadForm", "summary": "Delete a lead form", "description": "Deletes the form. Its page stops working at once, so a website that shows the form shows nothing. The leads it brought in stay in the book with no `lead_form_id`.", "tags": [ "Lead forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The form does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lead-forms/{id}/turn-on-auto-reply": { "post": { "operationId": "turnOnLeadFormAutoReply", "summary": "Turn on a lead form's auto-reply", "description": "Turns on the reply that the form sends to each person who fills it in, with the words in `config.thanks`. The reply is on when the response comes back, and the response is the form. A reply that is already on stays on. A key with the `no_sending` limit cannot use this endpoint.", "tags": [ "Lead forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lead_form", "description": "The type of this record. Always `lead_form`.", "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "description": "Stable identifier for the lead form." }, "name": { "type": "string", "description": "The name the broker gave the form. Leads show it as `lead_form_name`." }, "slug": { "type": "string", "description": "The form's part of `url`. Unique across BrokerPlus." }, "url": { "type": "string", "description": "The page where somebody fills in the form. Put it in an `iframe` on a website, or link to it. It shows nothing while `enabled` is false." }, "enabled": { "type": "boolean", "description": "True while the form takes answers. False hides the form and keeps its leads." }, "owner_user_id": { "type": "string", "description": "The broker who owns the form. Its leads go to this broker unless `routing` says another." }, "owner_name": { "nullable": true, "description": "The name of `owner_user_id`.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The whole form, as the form builder in BrokerPlus saves it: `headline`, `blurb`, `submitLabel`, `steps`, `questions` (each with `key`, `label`, `type`, `required`, `crm`, `options`, `step`, and `cond`), `thanks` (the thank-you screen and the auto-reply), `routing`, `tagging`, `spam`, `embed`, `subscribe`, and `savings`. Keys are camelCase here, because this is the builder's own format. Every form must ask everyone for a first name and an email." }, "lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every lead the form brought in. List them with `GET /v1/leads?lead_form_id=`." }, "recent_lead_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads the form brought in during the last 30 days." }, "converted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The leads from the form that left the Leads board (`archived_at` is set), the same number the Lead Forms screen shows as converted." }, "newest_lead_at": { "nullable": true, "description": "When the form last brought in a lead. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the form was made." }, "updated_at": { "type": "string", "description": "Last change to the form." } }, "required": [ "object", "id", "name", "slug", "url", "enabled", "owner_user_id", "owner_name", "config", "lead_count", "recent_lead_count", "converted_count", "newest_lead_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The form does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/custom-fields": { "get": { "operationId": "listCustomFields", "summary": "List custom field definitions", "description": "The custom fields the brokerage keeps, with their keys, types and options, in the brokerage's order. Leads use the `contact` fields.", "tags": [ "Custom fields" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "contact", "deal" ] }, "description": "Send `contact` or `deal` to list one kind. Omit it to list both." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "custom_field_definition", "description": "The type of this record. Always `custom_field_definition`.", "type": "string", "enum": [ "custom_field_definition" ] }, "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record the field is on. A lead uses the contact fields." }, "key": { "type": "string", "description": "Stable slug for the field. Use it to read, to write, and to filter a list with `custom_field[key]=value`." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "help_text": { "nullable": true, "description": "The brokerage's own instruction for what goes in the field.", "type": "string" }, "id": { "type": "string", "description": "Stable identifier for the field. Reads and writes use `key`; this is for matching records." }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form a write takes. Null for a field that starts blank.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The field's place in the brokerage's own order, lowest first." }, "created_at": { "type": "string", "description": "When the brokerage added the field." }, "updated_at": { "type": "string", "description": "Last change to the field's label, options or order." } }, "required": [ "object", "entity", "key", "label", "type", "options", "section", "help_text", "id", "default_value", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`entity` is not `contact` or `deal` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCustomField", "summary": "Create a custom field", "description": "Adds a field to every contact or every deal, the same as Settings > Custom Fields. The new field goes to the end of the order. Only a key that belongs to a brokerage admin can change custom fields. A label that makes the key of an archived field restores that field, with the answers it had.", "tags": [ "Custom fields" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record the field is on. A lead uses the contact fields." }, "label": { "type": "string", "minLength": 1, "maxLength": 60, "description": "What the brokerage calls the field on screen. BrokerPlus makes the field's `key` from it, and the key does not change when the label changes. A label that makes the key of an archived field restores that field and its answers." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. You cannot change the type after you create the field." }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": "The permitted values of a `select` or `multi_select` field, in the order to show them. Send the whole list. An option that is not in the list is removed, and the answers that use it stay on the records that have them. An option keeps its answers only when you send its label unchanged. Other types ignore this field." }, "section": { "description": "The group to show the field under. Defaults to `Custom Fields`.", "type": "string", "minLength": 1, "maxLength": 40 }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form as `PATCH /contacts/{id}/custom-fields/{key}`. A `select` default is one of `options`. Send null to make new records start blank. A change applies only to records made after it.", "type": "string", "maxLength": 160000 } }, "required": [ "entity", "label", "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "custom_field_definition", "description": "The type of this record. Always `custom_field_definition`.", "type": "string", "enum": [ "custom_field_definition" ] }, "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record the field is on. A lead uses the contact fields." }, "key": { "type": "string", "description": "Stable slug for the field. Use it to read, to write, and to filter a list with `custom_field[key]=value`." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "help_text": { "nullable": true, "description": "The brokerage's own instruction for what goes in the field.", "type": "string" }, "id": { "type": "string", "description": "Stable identifier for the field. Reads and writes use `key`; this is for matching records." }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form a write takes. Null for a field that starts blank.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The field's place in the brokerage's own order, lowest first." }, "created_at": { "type": "string", "description": "When the brokerage added the field." }, "updated_at": { "type": "string", "description": "Last change to the field's label, options or order." } }, "required": [ "object", "entity", "key", "label", "type", "options", "section", "help_text", "id", "default_value", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The label has no letters or numbers, a dropdown has no options, or the default is not a value the field takes (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A field with this key exists (ALREADY_EXISTS), or an archived field with this key has a different type (TYPE_MISMATCH).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/custom-fields/reorder": { "post": { "operationId": "reorderCustomFields", "summary": "Put custom fields in order", "description": "Sets the order of the contact fields or the deal fields, the same as a drag in Settings > Custom Fields. Admin keys only. Returns the fields of that entity in the new order.", "tags": [ "Custom fields" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record whose fields you put in order." }, "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "Field ids in the new order, first to last. A field that is not in the list keeps its place. An id from another brokerage or entity is ignored." } }, "required": [ "entity", "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "custom_field_definition", "description": "The type of this record. Always `custom_field_definition`.", "type": "string", "enum": [ "custom_field_definition" ] }, "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record the field is on. A lead uses the contact fields." }, "key": { "type": "string", "description": "Stable slug for the field. Use it to read, to write, and to filter a list with `custom_field[key]=value`." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "help_text": { "nullable": true, "description": "The brokerage's own instruction for what goes in the field.", "type": "string" }, "id": { "type": "string", "description": "Stable identifier for the field. Reads and writes use `key`; this is for matching records." }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form a write takes. Null for a field that starts blank.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The field's place in the brokerage's own order, lowest first." }, "created_at": { "type": "string", "description": "When the brokerage added the field." }, "updated_at": { "type": "string", "description": "Last change to the field's label, options or order." } }, "required": [ "object", "entity", "key", "label", "type", "options", "section", "help_text", "id", "default_value", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/custom-fields/{id}": { "patch": { "operationId": "updateCustomField", "summary": "Update a custom field", "description": "Changes the label, options, group, or default of a field. You cannot change the `key` or the `type`. When you remove the option that is the default, the default becomes null. Admin keys only.", "tags": [ "Custom fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "description": "A new label. The `key` stays the same, so reads, writes, and filters continue to work.", "type": "string", "minLength": 1, "maxLength": 60 }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": "The permitted values of a `select` or `multi_select` field, in the order to show them. Send the whole list. An option that is not in the list is removed, and the answers that use it stay on the records that have them. An option keeps its answers only when you send its label unchanged. Other types ignore this field." }, "section": { "description": "The group to show the field under.", "type": "string", "minLength": 1, "maxLength": 40 }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form as `PATCH /contacts/{id}/custom-fields/{key}`. A `select` default is one of `options`. Send null to make new records start blank. A change applies only to records made after it.", "type": "string", "maxLength": 160000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "custom_field_definition", "description": "The type of this record. Always `custom_field_definition`.", "type": "string", "enum": [ "custom_field_definition" ] }, "entity": { "type": "string", "enum": [ "contact", "deal" ], "description": "The kind of record the field is on. A lead uses the contact fields." }, "key": { "type": "string", "description": "Stable slug for the field. Use it to read, to write, and to filter a list with `custom_field[key]=value`." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "help_text": { "nullable": true, "description": "The brokerage's own instruction for what goes in the field.", "type": "string" }, "id": { "type": "string", "description": "Stable identifier for the field. Reads and writes use `key`; this is for matching records." }, "default_value": { "nullable": true, "description": "The answer every new contact or deal starts with, in the same text form a write takes. Null for a field that starts blank.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The field's place in the brokerage's own order, lowest first." }, "created_at": { "type": "string", "description": "When the brokerage added the field." }, "updated_at": { "type": "string", "description": "Last change to the field's label, options or order." } }, "required": [ "object", "entity", "key", "label", "type", "options", "section", "help_text", "id", "default_value", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A dropdown has no options, or the default is not a value the field takes (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live field in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveCustomField", "summary": "Archive a custom field", "description": "Removes the field from every form, the same as Delete in Settings > Custom Fields. BrokerPlus keeps the answers, and the data export still contains them. To restore the field, create a field with the same label and type. Admin keys only.", "tags": [ "Custom fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live field in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals": { "get": { "operationId": "listDeals", "summary": "List deals", "description": "The mortgage pipeline. To find the deal behind a record in another system, pass its id there as `external_reference`, or the lender's file number as `lender_file_ref`. Both match exactly.", "tags": [ "Deals" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lead", "active", "submitted", "approved", "funded", "closed", "dead", "declined", "cancelled", "expired", "withdrawn", "unknown" ] }, "description": "Filter by lifecycle status. Any other value gets `400 VALIDATION_ERROR`." }, { "name": "board_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the deals on this pipeline." }, { "name": "stage_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the deals in this stage. A stage belongs to one pipeline, so you do not need `board_id` with it. With both, a stage that is not on `board_id` returns no deals." }, { "name": "external_reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact match on a deal's id in another system: a Velocity or Filogix loan code, a Finmo application id, or a Velocity Forms id. Add `source` to name the system." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With `external_reference`: the system the reference belongs to (`velocity`, `velocity_forms`, `finmo`)." }, { "name": "lender_file_ref", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact match on the lender's own file number for the deal." }, { "name": "custom_field", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Filter by a deal custom field: `custom_field[]=`, for example `custom_field[lead_source]=Google`. The value takes the same text as a write. An empty value finds records with no answer. Send up to 10; a record must match all of them. Get the keys from `GET /v1/custom-fields?entity=deal`.", "style": "deepObject", "explode": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "A `custom_field` key the brokerage does not have on a deal, or a value that does not fit the field (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDeal", "summary": "Create a deal", "description": "Open a deal for the key's broker. The deal lands on the broker's default pipeline for its type, or on `board_id` if you name one, and takes that pipeline's team. Attach borrowers with `contacts`. The mortgage application is not created here. Supports `Idempotency-Key`.", "tags": [ "Deals" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ], "description": "Deal type. Decides which pipeline the deal lands on when you do not name one." }, "board_id": { "description": "Pipeline to land on. Must belong to the broker's team. Omit to use the broker's default pipeline for the type.", "nullable": true, "type": "string" }, "stage_id": { "description": "Stage within `board_id`. Omit to land on the pipeline's first stage. Requires `board_id`.", "nullable": true, "type": "string" }, "closing_at": { "description": "Scheduled closing date. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Returns YYYY-MM-DD.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "contacts": { "description": "Borrowers to attach on creation. Partners attach through their own endpoints.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact in your brokerage." }, "role": { "description": "Their part in the deal. Defaults to `primary_applicant`.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney" ] } }, "required": [ "contact_id" ], "additionalProperties": false } } }, "required": [ "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A contact is not in your brokerage (INVALID_PARTY), the pipeline is not the broker's (INVALID_BOARD), or the stage is not on that pipeline (INVALID_STAGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker has no pipeline for this deal type (BROKER_HAS_NO_BOARDS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}": { "get": { "operationId": "getDeal", "summary": "Retrieve a deal", "description": "A single deal by id, with its stage and the contacts attached to it.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDeal", "summary": "Update a deal", "description": "Change the status, stage, owner, dates, name, lender file number, underwriter or lender. The API applies the same lifecycle rules as BrokerPlus. The underwriter and the lender save first, so a stage move in the same request is checked against them. The other fields commit together. It returns 409 if the deal changes during validation.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Lifecycle status. Funding requires anti-money laundering clearance for every borrower. Repeated funding keeps the original funded date. Setting a lead-backed deal to active archives its lead record.", "type": "string", "enum": [ "active", "dead", "closed", "funded" ] }, "type": { "description": "Deal type, the same values as on create. The change is the same as in the dashboard. BrokerPlus calculates the total loan amount and the mortgage insurance premium again for the new type. A change into a renewal type, out of one, or between `renewal_same_lender` and `renewal_diff_lender` replaces the renewal disclosures and attestations that the old type resolved, so they must be done again. The deal stays on its pipeline and in its stage, and the stage requirements are not checked again.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "stage_id": { "description": "Stage in the current pipeline. Forward moves must meet the stage requirements. Null clears the stage and its entry date.", "nullable": true, "type": "string" }, "assigned_broker_id": { "description": "Active broker in the brokerage. Reassignment transfers eligible open work. Ineligible tasks keep their assignees. Null clears the owner but preserves required request and calendar owners.", "nullable": true, "type": "string" }, "closing_at": { "description": "Scheduled closing date. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Returns YYYY-MM-DD.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "maturity_date": { "description": "Mortgage maturity date. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Returns YYYY-MM-DD.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "underwriter_id": { "description": "Active user in the brokerage who underwrites the deal. No work moves with it. Null clears it.", "nullable": true, "type": "string" }, "lender_id": { "description": "A lender from `GET /lenders`. Null clears it.", "nullable": true, "type": "string" }, "name": { "description": "A name for the deal. Null or an empty string returns the deal to the brokerage's naming pattern.", "nullable": true, "type": "string", "maxLength": 120 }, "lender_file_ref": { "description": "The lender's own file number for this deal. Null clears it.", "nullable": true, "type": "string", "maxLength": 80 }, "funded_at": { "description": "The actual funding date of a funded deal, or of a deal that is already closed, such as an imported completed file. The status stays closed. An imported file that its source system marked funded takes the date as is. On any other closed deal the date counts the deal as funded, so it requires the same AML clearance as setting status to funded. Accepts YYYY-MM-DD or an ISO 8601 timestamp.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The broker, underwriter, lender or stage is not in your brokerage (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker has view-only access, or the deal is locked (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Stage requirements are not met (STAGE_REQUIREMENTS_UNMET), `funded_at` was sent for a deal that is not funded (NOT_FUNDED), or the deal changed during validation (CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "Anti-money laundering requirements prevent funding (AML_GATE_BLOCKED). The public API does not accept an acknowledgement override.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveDeal", "summary": "Archive a deal", "description": "Removes the deal from its pipeline, reports and searches, and cancels its open tasks. The deal is not erased. Restore it with `POST /v1/deals/{id}/restore`, or a broker can restore it in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker has view-only access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/restore": { "post": { "operationId": "restoreDeal", "summary": "Restore an archived deal", "description": "Puts an archived deal back on its pipeline. When its pipeline was deleted, the deal goes to the first pipeline of the same team that takes its type. The tasks the archive cancelled stay cancelled.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The deal is not archived (NOT_ARCHIVED), or BrokerPlus merged it into a different deal and it can't come back (MERGED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/duplicate": { "post": { "operationId": "duplicateDeal", "summary": "Duplicate a deal", "description": "Makes a new deal with the same people and the primary application, at the first stage of the same pipeline, assigned to the broker your key acts as. Submissions, funding, compliance and documents are not copied. The copy is a new deal to automations too. Nothing is sent to anyone: to ask the borrowers on the copy for a credit consent, use BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "The new file's deal type. Leave it out to keep the original's type.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "carry_participants": { "default": true, "description": "Copy every person on the deal. Send false to copy only the primary applicant; the co-applicants, guarantors and partners stay on the original.", "type": "boolean" }, "archive_original": { "default": false, "description": "Archive the original once the copy exists, as `DELETE /v1/deals/{id}` does. You can restore it with `POST /v1/deals/{id}/restore`.", "type": "boolean" } }, "required": [ "carry_participants", "archive_original" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/participants": { "get": { "operationId": "listDealParticipants", "summary": "List who is on a deal", "description": "Every contact attached to the deal with their role: the borrowers and the partners (realtor, lawyer, lender contact, and so on). `is_partner` separates the two. Both agents on a purchase hold the same `realtor` role, so the seller's agent is told from the buyer's by `role_label` - the brokerage's own word for the seat.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_participant", "description": "The type of this record. Always `deal_participant`.", "type": "string", "enum": [ "deal_participant" ] }, "id": { "type": "string", "description": "Same as `contact_id`. A participant is identified by its contact on this deal." }, "contact_id": { "type": "string", "description": "The contact. Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ], "description": "Their part in the deal. `primary_applicant`, `co_applicant`, `guarantor`, `cosigner` and `power_of_attorney` are borrowers; every other value is a partner on the file. A `cosigner` is on title and on the mortgage; a `guarantor` is not." }, "role_label": { "nullable": true, "description": "The brokerage's own word for a partner whose role is `other`, e.g. `Home Inspector`. Null on any other role. This is also where the two sides of a purchase are told apart: `role` is the same `realtor` for both agents on a sale, so a brokerage that needs the distinction names the seats itself, as `Listing Realtor` and `Buying Realtor`.", "type": "string" }, "is_partner": { "type": "boolean", "description": "True for a partner role, false for a borrower role." }, "lender_approval_number": { "nullable": true, "description": "The lender's approval number for this file. Only set on a `lender_contact`.", "type": "string" }, "first_name": { "nullable": true, "description": "The contact's given name, for display. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "The contact's family name, for display. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "The contact's business name, for display. Null on an individual.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "is_partner", "lender_approval_number", "first_name", "last_name", "company_name" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "attachDealParticipant", "summary": "Put a contact on a deal", "description": "Attaches a contact in a role. A contact can hold one role per deal; attaching one already on the deal returns 409. Attaching a partner fires the `deal.partner_added` automation trigger.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact in your brokerage." }, "role": { "description": "Defaults to `primary_applicant`.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "role_label": { "description": "Your own word for the partner's seat, e.g. `Listing Realtor`. Only valid with `role: other`, and the way to tell the two agents on a purchase apart.", "nullable": true, "type": "string", "maxLength": 60 }, "lender_approval_number": { "description": "The lender's approval number for this file. Only valid with `role: lender_contact`.", "nullable": true, "type": "string", "maxLength": 60 } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_participant", "description": "The type of this record. Always `deal_participant`.", "type": "string", "enum": [ "deal_participant" ] }, "id": { "type": "string", "description": "Same as `contact_id`. A participant is identified by its contact on this deal." }, "contact_id": { "type": "string", "description": "The contact. Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ], "description": "Their part in the deal. `primary_applicant`, `co_applicant`, `guarantor`, `cosigner` and `power_of_attorney` are borrowers; every other value is a partner on the file. A `cosigner` is on title and on the mortgage; a `guarantor` is not." }, "role_label": { "nullable": true, "description": "The brokerage's own word for a partner whose role is `other`, e.g. `Home Inspector`. Null on any other role. This is also where the two sides of a purchase are told apart: `role` is the same `realtor` for both agents on a sale, so a brokerage that needs the distinction names the seats itself, as `Listing Realtor` and `Buying Realtor`.", "type": "string" }, "is_partner": { "type": "boolean", "description": "True for a partner role, false for a borrower role." }, "lender_approval_number": { "nullable": true, "description": "The lender's approval number for this file. Only set on a `lender_contact`.", "type": "string" }, "first_name": { "nullable": true, "description": "The contact's given name, for display. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "The contact's family name, for display. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "The contact's business name, for display. Null on an individual.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "is_partner", "lender_approval_number", "first_name", "last_name", "company_name" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The contact is not in your brokerage (INVALID_PARTY), a `role_label` was sent without `role: other` (INVALID_ROLE_LABEL), or a `lender_approval_number` was sent without `role: lender_contact` (INVALID_APPROVAL_NUMBER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The contact is already on the deal (PARTY_ALREADY_ON_DEAL).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/participants/{contactId}": { "patch": { "operationId": "updateDealParticipant", "summary": "Change a partner's role on a deal", "description": "Changes a partner's role, label, or approval number. A role moving off `other` clears the label; one moving off `lender_contact` clears the approval number. Borrowers are not editable here.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "A partner role. A borrower's role cannot change here; it is set by the application.", "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "role_label": { "description": "Your own word for the partner's seat, e.g. `Listing Realtor`. Only valid with `role: other`. Send null to clear.", "nullable": true, "type": "string", "maxLength": 60 }, "lender_approval_number": { "description": "The lender's approval number. Only valid on a `lender_contact`. Send null to clear.", "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_participant", "description": "The type of this record. Always `deal_participant`.", "type": "string", "enum": [ "deal_participant" ] }, "id": { "type": "string", "description": "Same as `contact_id`. A participant is identified by its contact on this deal." }, "contact_id": { "type": "string", "description": "The contact. Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ], "description": "Their part in the deal. `primary_applicant`, `co_applicant`, `guarantor`, `cosigner` and `power_of_attorney` are borrowers; every other value is a partner on the file. A `cosigner` is on title and on the mortgage; a `guarantor` is not." }, "role_label": { "nullable": true, "description": "The brokerage's own word for a partner whose role is `other`, e.g. `Home Inspector`. Null on any other role. This is also where the two sides of a purchase are told apart: `role` is the same `realtor` for both agents on a sale, so a brokerage that needs the distinction names the seats itself, as `Listing Realtor` and `Buying Realtor`.", "type": "string" }, "is_partner": { "type": "boolean", "description": "True for a partner role, false for a borrower role." }, "lender_approval_number": { "nullable": true, "description": "The lender's approval number for this file. Only set on a `lender_contact`.", "type": "string" }, "first_name": { "nullable": true, "description": "The contact's given name, for display. Null on a company.", "type": "string" }, "last_name": { "nullable": true, "description": "The contact's family name, for display. Null on a company.", "type": "string" }, "company_name": { "nullable": true, "description": "The contact's business name, for display. Null on an individual.", "type": "string" } }, "required": [ "object", "id", "contact_id", "role", "role_label", "is_partner", "lender_approval_number", "first_name", "last_name", "company_name" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `role_label` without `role: other` (INVALID_ROLE_LABEL), or a `lender_approval_number` without `role: lender_contact` (INVALID_APPROVAL_NUMBER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact is not on the deal as a partner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "detachDealParticipant", "summary": "Take a contact off a deal", "description": "Removes the contact from the deal. A borrower with application detail on file cannot be removed until that detail is cleared in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The borrower has application detail on this deal (HAS_PROFILE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/participant-seats": { "get": { "operationId": "listParticipantSeats", "summary": "List the team's participant seats", "description": "The seats the key's active team keeps on its deals, in deal card order: a listing realtor, a lawyer, an underwriter. A seat names a participant before anybody fills it, so a stage requirement or an automation can name it. For the seats of one deal and whether that deal shows each one, use `GET /v1/deals/{id}/participant-seats`.", "tags": [ "Deals" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The team's seats, in deal card order." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createParticipantSeat", "summary": "Add a participant seat", "description": "Adds a seat to a team's deals. By default it is pinned: every deal the team opens from now on shows it, and open deals do not change. With `deal_id`, the seat goes on that deal's team and that deal shows it now. Adding a seat the team removed earlier brings it back. Only a member of the team can add one.", "tags": [ "Deals" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "A curated participant role, for example `lawyer`. Send `role` or `role_label`, not both.", "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client" ] }, "role_label": { "description": "The brokerage's own word for the seat, for example `Listing Realtor`. A word the brokerage already uses in another case is matched, so `listing realtor` becomes the same seat. Send `role` or `role_label`, not both.", "type": "string", "minLength": 1, "maxLength": 60 }, "pinned": { "description": "Defaults to `true`: every deal the team opens from now on shows the seat. Open deals do not change.", "type": "boolean" }, "default_contact_id": { "description": "A contact on the seat's team who sits in the seat on each new deal.", "nullable": true, "type": "string" }, "deal_id": { "description": "The deal you are looking at. The seat goes on that deal's team, and that deal shows it now. Without it, the seat goes on the key's active team.", "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid (VALIDATION_ERROR), the default contact is not on the team (INVALID_CONTACT), or the broker is not on a team they can change (NO_TEAM, READ_ONLY_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal in `deal_id` does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team already has this seat (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/participant-seats/{id}": { "get": { "operationId": "getParticipantSeat", "summary": "Retrieve a participant seat", "description": "One seat of a team the broker can see.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateParticipantSeat", "summary": "Update a participant seat", "description": "Pins or unpins a seat, or changes its default person. Neither change touches open deals. A seat's role cannot change: add a new seat and remove this one. Only a member of the seat's team can change it.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned": { "description": "`true` pins the seat from now: deals opened from now on show it, and open deals do not change. `false` stops new deals showing it.", "type": "boolean" }, "default_contact_id": { "description": "A contact on the seat's team who sits in the seat on each new deal. Send null to clear it.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid (VALIDATION_ERROR), or the default contact is not on the team (INVALID_CONTACT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The seat does not exist, or the broker is not on its team (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteParticipantSeat", "summary": "Remove a participant seat", "description": "Takes a seat off the team's deals. The people already in that seat on a deal stay on the deal. A stage that requires the seat blocks the removal: remove the requirement first.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The seat does not exist, or the broker is not on its team (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A stage requires this seat (SEAT_REQUIRED). `details.stages` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/participant-seats": { "get": { "operationId": "listDealParticipantSeats", "summary": "List a deal's participant seats", "description": "Every seat of the deal's team, with `on_deal` true for each seat this deal shows. The seats are the deal's team's, which can differ from the key's active team.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." }, "deal_id": { "type": "string", "description": "The deal that the answer in `on_deal` is about." }, "on_deal": { "type": "boolean", "description": "True when this deal shows the seat. A deal shows a seat that was pinned before it opened, unless the deal dismissed it, and a seat the deal adopted." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at", "deal_id", "on_deal" ], "additionalProperties": false }, "description": "The deal's team's seats, in deal card order." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/participant-seats/{seatId}/adopt": { "post": { "operationId": "adoptDealParticipantSeat", "summary": "Show a seat on a deal", "description": "This deal shows the seat, for example one the team pinned after the deal opened. Other deals do not change. Calling it again changes nothing.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "seatId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." }, "deal_id": { "type": "string", "description": "The deal that the answer in `on_deal` is about." }, "on_deal": { "type": "boolean", "description": "True when this deal shows the seat. A deal shows a seat that was pinned before it opened, unless the deal dismissed it, and a seat the deal adopted." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at", "deal_id", "on_deal" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the seat does not exist, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/participant-seats/{seatId}/dismiss": { "post": { "operationId": "dismissDealParticipantSeat", "summary": "Hide a seat on a deal", "description": "This deal stops showing the seat, for example a listing realtor on a private sale. The person in the seat, if any, stays on the deal. Other deals do not change. Calling it again changes nothing.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "seatId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "participant_seat", "description": "The type of this record. Always `participant_seat`.", "type": "string", "enum": [ "participant_seat" ] }, "id": { "type": "string", "description": "Stable identifier for the seat." }, "team_id": { "type": "string", "description": "The team that keeps the seat on its deals." }, "kind": { "type": "string", "description": "The key that names the seat everywhere else: a stage requirement, an automation recipient, a participant on a deal. A curated role is the role itself, for example `realtor`. The brokerage's own word is `label:` and the word, for example `label:Listing Realtor`." }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "bdm", "insurance", "financial_planner", "accountant", "builder", "past_client", "other" ], "description": "The participant role the seat is for. `other` when the seat is the brokerage's own word, which is in `role_label`. Matches `role` on `GET /v1/deals/{id}/participants`." }, "role_label": { "nullable": true, "description": "The brokerage's own word for the seat, for example `Listing Realtor`. Null on a curated role.", "type": "string" }, "name": { "type": "string", "description": "The seat name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The seat's place on the deal card, from 0." }, "pinned": { "type": "boolean", "description": "True when every new deal of the team shows the seat, filled or not. A deal opened before the pin does not take it until it adopts the seat. False keeps the word for stage requirements and automations without showing a slot." }, "pinned_at": { "nullable": true, "description": "When the seat was pinned. Deals opened after this show the seat. Null when it is not pinned.", "type": "string" }, "default_contact_id": { "nullable": true, "description": "The person who sits in the seat on each new deal, when the team always uses the same one. Put on a deal when it opens; changing it does not change open deals. Null for none.", "type": "string" }, "default_contact_name": { "nullable": true, "description": "The default person's name, for display. Null for none.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was made." }, "updated_at": { "type": "string", "description": "When the seat last changed." }, "deal_id": { "type": "string", "description": "The deal that the answer in `on_deal` is about." }, "on_deal": { "type": "boolean", "description": "True when this deal shows the seat. A deal shows a seat that was pinned before it opened, unless the deal dismissed it, and a seat the deal adopted." } }, "required": [ "object", "id", "team_id", "kind", "role", "role_label", "name", "position", "pinned", "pinned_at", "default_contact_id", "default_contact_name", "created_at", "updated_at", "deal_id", "on_deal" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the seat does not exist, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/team": { "get": { "operationId": "listDealTeam", "summary": "List who works a deal", "description": "The users in your brokerage who hold a role on the deal, e.g. `Sales Manager` or `Closing Officer`. Each role holds one user. These are your own staff, not contacts: an outside person such as a lawyer is a participant.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "The brokerage's own word for the role, e.g. `Client Care Manager`." }, "user_id": { "type": "string", "description": "The user who holds the role. Resolve against `GET /users/{id}`." } }, "required": [ "role", "user_id" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setDealTeamRole", "summary": "Put a user in a role on a deal", "description": "Fills a role with a user. If the role is already held, the new user replaces the old one. The role name is matched without regard to case, so `sales manager` fills an existing `Sales Manager` role.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The role to fill, e.g. `Sales Manager`. A deal holds one user for each role. Filling a role that is already held replaces its user." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "An active user in your brokerage." } }, "required": [ "role", "user_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "role": { "type": "string", "description": "The brokerage's own word for the role, e.g. `Client Care Manager`." }, "user_id": { "type": "string", "description": "The user who holds the role. Resolve against `GET /users/{id}`." } }, "required": [ "role", "user_id" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The user is not an active user in your brokerage (INVALID_USER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/team/{role}": { "delete": { "operationId": "clearDealTeamRole", "summary": "Empty a role on a deal", "description": "Removes the user from the role. Put the role name in the path, URL-encoded, e.g. `Sales%20Manager`. Emptying a role that nobody holds also succeeds.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/referral-partner": { "post": { "operationId": "setDealReferralPartner", "summary": "Set who referred a deal", "description": "Credits a referral partner with the deal, as the referral picker on the deal page does. Send `contact_id` to name a contact, or `name` for a partner who is not a contact. A contact becomes a partner the first time you name them, and a `name` reuses the brokerage's partner with that name. A deal linked to other files moves with them. Returns the deal.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "A contact in your brokerage. BrokerPlus files them as a partner if they are not one yet.", "type": "string" }, "name": { "description": "A partner who is not a contact, by name. BrokerPlus reuses a partner with the same name.", "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "description": "What the partner is, e.g. `realtor`, `lawyer`, `financial_planner`, or `past_client`.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 40 } }, "additionalProperties": false, "description": "The partner who referred the deal. Send `contact_id` or `name`." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal, or the contact in `contact_id`, is not in your brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "clearDealReferralPartner", "summary": "Clear who referred a deal", "description": "Removes the referral partner from the deal. Clearing a deal that has none also succeeds. Returns the deal.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/stage-requirements": { "get": { "operationId": "checkDealStageRequirements", "summary": "Check a stage before moving a deal", "description": "Tells you what the deal needs before it can move to a stage, without moving it. The check is the same one that `PATCH /deals/{id}` runs, so an empty `missing` list means the move will pass the stage requirements.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "stage_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required. The stage to check, on the deal's own pipeline." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "The stage that was checked." }, "stage_name": { "type": "string", "description": "Display name of that stage." }, "ready": { "type": "boolean", "description": "True when the deal can move to the stage now." }, "missing": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The requirement. The same key that a 409 STAGE_REQUIREMENTS_UNMET response carries, e.g. `participants.lawyer`." }, "label": { "type": "string", "description": "The requirement's display name, e.g. `Lawyer`." }, "kind": { "type": "string", "enum": [ "field", "checkpoint", "custom_field" ], "description": "`field` is a value on the deal. `checkpoint` is a checklist step to mark done. `custom_field` is one of your deal custom fields to fill in." } }, "required": [ "key", "label", "kind" ], "additionalProperties": false }, "description": "What the deal needs before it can move. Empty when `ready` is true." } }, "required": [ "stage_id", "stage_name", "ready", "missing" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "No `stage_id`, or the stage is not on the deal's pipeline (INVALID_STAGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/commission": { "get": { "operationId": "getDealCommission", "summary": "Read a deal's commission", "description": "The money the brokerage earns on the deal, with its line items and its splits. The API key's broker must be able to see compensation on the deal: the deal's own broker, a brokerage admin, or a team member with the `view_commission` grant.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "commission", "description": "The type of this record. Always `commission`.", "type": "string", "enum": [ "commission" ] }, "id": { "type": "string", "description": "Stable identifier for the commission." }, "deal_id": { "type": "string", "description": "The deal. One commission per deal." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ], "description": "`pending` until the lender confirms, `paid` when the money arrived, `clawed_back` when it was taken back." }, "lender_id": { "nullable": true, "description": "The paying lender, when it is one of yours. Resolve against `GET /lenders`.", "type": "string" }, "lender_name": { "nullable": true, "description": "The paying lender's name, for a lender not in your list.", "type": "string" }, "funded_amount": { "nullable": true, "description": "Dollars funded, the basis for the finder's fee.", "type": "number" }, "finder_fee_bps": { "nullable": true, "description": "Finder's fee in basis points, as the broker typed it (85 is 0.85%).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "finder_fee_amount": { "nullable": true, "description": "Finder's fee in dollars. This figure is authoritative over the basis points.", "type": "number" }, "bonus_bps": { "nullable": true, "description": "Volume bonus in basis points.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bonus_amount": { "nullable": true, "description": "Volume bonus in dollars.", "type": "number" }, "buydown_amount": { "nullable": true, "description": "Dollars handed back to buy the rate down. `gross_amount` is already net of it.", "type": "number" }, "buydown_reason": { "nullable": true, "description": "The broker's note on why they bought the rate down.", "type": "string" }, "gross_amount": { "nullable": true, "description": "Dollars the brokerage earns before splits. The sum of the line items less the buydown, whenever line items exist.", "type": "number" }, "expected_payout_at": { "nullable": true, "description": "When the lender is expected to pay.", "type": "string" }, "paid_at": { "nullable": true, "description": "When the lender paid.", "type": "string" }, "clawback_amount": { "nullable": true, "description": "Dollars taken back, when the deal paid out early.", "type": "number" }, "clawback_at": { "nullable": true, "description": "When it was taken back.", "type": "string" }, "clawback_reason": { "nullable": true, "description": "Why.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments on every change to the money. What the accounting posting is keyed on." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_line", "description": "The type of this record. Always `commission_line`.", "type": "string", "enum": [ "commission_line" ] }, "id": { "type": "string", "description": "Stable identifier for the line." }, "kind": { "type": "string", "enum": [ "finder_fee", "volume_bonus", "mpp", "other" ], "description": "Where the money comes from: the lender's finder's fee, a volume bonus, mortgage protection (`mpp`), or `other`." }, "label": { "nullable": true, "description": "Your own label. Only with kind `other`.", "type": "string" }, "mpp_source": { "nullable": true, "description": "Only with kind `mpp`: paid through the lender, or direct by the insurer.", "type": "string", "enum": [ "lender_paid", "direct" ] }, "amount": { "type": "number", "description": "Dollars. What was or is expected to be paid on this line." }, "status": { "type": "string", "enum": [ "expected", "invoiced", "received" ], "description": "`expected` until invoiced, then `received` when the money arrived." }, "expected_at": { "nullable": true, "description": "When the money is expected.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived. Null until it did.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "created_at": { "type": "string", "description": "When the line was added." }, "updated_at": { "type": "string", "description": "When the line last changed." } }, "required": [ "object", "id", "kind", "label", "mpp_source", "amount", "status", "expected_at", "received_at", "notes", "created_at", "updated_at" ], "additionalProperties": false }, "description": "What the deal pays, by source." }, "splits": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_split", "description": "The type of this record. Always `commission_split`.", "type": "string", "enum": [ "commission_split" ] }, "id": { "type": "string", "description": "Stable identifier for the split." }, "payee_type": { "type": "string", "enum": [ "broker", "house", "franchise", "referral", "other" ], "description": "Who gets the share: one of your brokers, the house, a franchise, a referral partner, or another party." }, "broker_user_id": { "nullable": true, "description": "With `broker`: the user who gets the share. Resolve against `GET /users`.", "type": "string" }, "payee_label": { "nullable": true, "description": "With any other payee type: the party's name.", "type": "string" }, "share_percent": { "nullable": true, "description": "Percent of the parent pool. Of the gross at the top level.", "type": "number" }, "share_amount": { "nullable": true, "description": "Dollars, when the share is a fixed amount.", "type": "number" }, "role": { "nullable": true, "description": "Your own label for the payee's part in the deal.", "type": "string" }, "parent_split_id": { "nullable": true, "description": "The split this one carves out of, when a brokerage divides its own share. Null at the top level.", "type": "string" }, "created_at": { "type": "string", "description": "When the split was added." } }, "required": [ "object", "id", "payee_type", "broker_user_id", "payee_label", "share_percent", "share_amount", "role", "parent_split_id", "created_at" ], "additionalProperties": false }, "description": "How the gross is allocated. An allocation is not a payment." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded the commission. Resolve against `GET /users`. Null when it was imported.", "type": "string" }, "created_at": { "type": "string", "description": "When the commission was recorded." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "status", "lender_id", "lender_name", "funded_amount", "finder_fee_bps", "finder_fee_amount", "bonus_bps", "bonus_amount", "buydown_amount", "buydown_reason", "gross_amount", "expected_payout_at", "paid_at", "clawback_amount", "clawback_at", "clawback_reason", "notes", "revision", "line_items", "splits", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The API key's broker cannot see compensation on this deal (COMMISSION_ACCESS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not found, or it has no commission yet (NO_COMMISSION).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealCommission", "summary": "Record a deal's commission", "description": "Creates the commission on a deal that has none. Every figure is what you send; the API derives nothing from a rate sheet. When line items are sent, `gross_amount` becomes their sum less the buydown. A change to the money is posted to the brokerage's connected accounting system.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ], "description": "`pending` until the lender confirms, `paid` when the money arrived, `clawed_back` when it was taken back." }, "lender_id": { "description": "A lender in your list.", "nullable": true, "type": "string" }, "lender_name": { "description": "The paying lender's name.", "nullable": true, "type": "string", "maxLength": 255 }, "funded_amount": { "description": "Dollars funded.", "nullable": true, "type": "number" }, "finder_fee_bps": { "description": "Finder's fee in basis points.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "finder_fee_amount": { "description": "Finder's fee in dollars.", "nullable": true, "type": "number" }, "bonus_bps": { "description": "Volume bonus in basis points.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bonus_amount": { "description": "Volume bonus in dollars.", "nullable": true, "type": "number" }, "buydown_amount": { "description": "Buydown in dollars.", "nullable": true, "type": "number" }, "buydown_reason": { "description": "Why the rate was bought down.", "nullable": true, "type": "string", "maxLength": 1000 }, "gross_amount": { "description": "Gross in dollars. Ignored when line items exist: the gross is then their sum less the buydown.", "nullable": true, "type": "number" }, "expected_payout_at": { "description": "When the lender is expected to pay.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "paid_at": { "description": "When the lender paid.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "clawback_amount": { "description": "Dollars taken back.", "nullable": true, "type": "number" }, "clawback_at": { "description": "When.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "clawback_reason": { "description": "Why.", "nullable": true, "type": "string", "maxLength": 1000 }, "notes": { "description": "Free text.", "nullable": true, "type": "string", "maxLength": 2000 }, "line_items": { "description": "Replaces every line item when sent.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "finder_fee", "volume_bonus", "mpp", "other" ], "description": "Where the money comes from: the lender's finder's fee, a volume bonus, mortgage protection (`mpp`), or `other`." }, "label": { "description": "Your own label. Only kept with kind `other`.", "nullable": true, "type": "string", "maxLength": 120 }, "mpp_source": { "nullable": true, "description": "Only with kind `mpp`: paid through the lender, or direct by the insurer.", "type": "string", "enum": [ "lender_paid", "direct" ] }, "amount": { "type": "number", "minimum": 0, "description": "Dollars." }, "status": { "description": "Defaults to `expected`.", "type": "string", "enum": [ "expected", "invoiced", "received" ] }, "expected_at": { "description": "When the money is expected.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "received_at": { "description": "When it arrived.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "notes": { "description": "Free text.", "nullable": true, "type": "string", "maxLength": 1000 } }, "required": [ "kind", "amount" ], "additionalProperties": false } }, "splits": { "description": "Replaces every split when sent.", "type": "array", "items": { "type": "object", "properties": { "payee_type": { "description": "Defaults to `broker`.", "type": "string", "enum": [ "broker", "house", "franchise", "referral", "other" ] }, "broker_user_id": { "description": "With `broker`: a user in your brokerage.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 255 }, "payee_label": { "description": "With any other payee type: the party's name.", "nullable": true, "type": "string", "maxLength": 120 }, "share_percent": { "description": "Percent of the gross.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "share_amount": { "description": "Dollars, when the share is a fixed amount.", "nullable": true, "type": "number" }, "role": { "description": "Your own label for the payee's part.", "nullable": true, "type": "string", "maxLength": 100 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "commission", "description": "The type of this record. Always `commission`.", "type": "string", "enum": [ "commission" ] }, "id": { "type": "string", "description": "Stable identifier for the commission." }, "deal_id": { "type": "string", "description": "The deal. One commission per deal." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ], "description": "`pending` until the lender confirms, `paid` when the money arrived, `clawed_back` when it was taken back." }, "lender_id": { "nullable": true, "description": "The paying lender, when it is one of yours. Resolve against `GET /lenders`.", "type": "string" }, "lender_name": { "nullable": true, "description": "The paying lender's name, for a lender not in your list.", "type": "string" }, "funded_amount": { "nullable": true, "description": "Dollars funded, the basis for the finder's fee.", "type": "number" }, "finder_fee_bps": { "nullable": true, "description": "Finder's fee in basis points, as the broker typed it (85 is 0.85%).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "finder_fee_amount": { "nullable": true, "description": "Finder's fee in dollars. This figure is authoritative over the basis points.", "type": "number" }, "bonus_bps": { "nullable": true, "description": "Volume bonus in basis points.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bonus_amount": { "nullable": true, "description": "Volume bonus in dollars.", "type": "number" }, "buydown_amount": { "nullable": true, "description": "Dollars handed back to buy the rate down. `gross_amount` is already net of it.", "type": "number" }, "buydown_reason": { "nullable": true, "description": "The broker's note on why they bought the rate down.", "type": "string" }, "gross_amount": { "nullable": true, "description": "Dollars the brokerage earns before splits. The sum of the line items less the buydown, whenever line items exist.", "type": "number" }, "expected_payout_at": { "nullable": true, "description": "When the lender is expected to pay.", "type": "string" }, "paid_at": { "nullable": true, "description": "When the lender paid.", "type": "string" }, "clawback_amount": { "nullable": true, "description": "Dollars taken back, when the deal paid out early.", "type": "number" }, "clawback_at": { "nullable": true, "description": "When it was taken back.", "type": "string" }, "clawback_reason": { "nullable": true, "description": "Why.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments on every change to the money. What the accounting posting is keyed on." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_line", "description": "The type of this record. Always `commission_line`.", "type": "string", "enum": [ "commission_line" ] }, "id": { "type": "string", "description": "Stable identifier for the line." }, "kind": { "type": "string", "enum": [ "finder_fee", "volume_bonus", "mpp", "other" ], "description": "Where the money comes from: the lender's finder's fee, a volume bonus, mortgage protection (`mpp`), or `other`." }, "label": { "nullable": true, "description": "Your own label. Only with kind `other`.", "type": "string" }, "mpp_source": { "nullable": true, "description": "Only with kind `mpp`: paid through the lender, or direct by the insurer.", "type": "string", "enum": [ "lender_paid", "direct" ] }, "amount": { "type": "number", "description": "Dollars. What was or is expected to be paid on this line." }, "status": { "type": "string", "enum": [ "expected", "invoiced", "received" ], "description": "`expected` until invoiced, then `received` when the money arrived." }, "expected_at": { "nullable": true, "description": "When the money is expected.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived. Null until it did.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "created_at": { "type": "string", "description": "When the line was added." }, "updated_at": { "type": "string", "description": "When the line last changed." } }, "required": [ "object", "id", "kind", "label", "mpp_source", "amount", "status", "expected_at", "received_at", "notes", "created_at", "updated_at" ], "additionalProperties": false }, "description": "What the deal pays, by source." }, "splits": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_split", "description": "The type of this record. Always `commission_split`.", "type": "string", "enum": [ "commission_split" ] }, "id": { "type": "string", "description": "Stable identifier for the split." }, "payee_type": { "type": "string", "enum": [ "broker", "house", "franchise", "referral", "other" ], "description": "Who gets the share: one of your brokers, the house, a franchise, a referral partner, or another party." }, "broker_user_id": { "nullable": true, "description": "With `broker`: the user who gets the share. Resolve against `GET /users`.", "type": "string" }, "payee_label": { "nullable": true, "description": "With any other payee type: the party's name.", "type": "string" }, "share_percent": { "nullable": true, "description": "Percent of the parent pool. Of the gross at the top level.", "type": "number" }, "share_amount": { "nullable": true, "description": "Dollars, when the share is a fixed amount.", "type": "number" }, "role": { "nullable": true, "description": "Your own label for the payee's part in the deal.", "type": "string" }, "parent_split_id": { "nullable": true, "description": "The split this one carves out of, when a brokerage divides its own share. Null at the top level.", "type": "string" }, "created_at": { "type": "string", "description": "When the split was added." } }, "required": [ "object", "id", "payee_type", "broker_user_id", "payee_label", "share_percent", "share_amount", "role", "parent_split_id", "created_at" ], "additionalProperties": false }, "description": "How the gross is allocated. An allocation is not a payment." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded the commission. Resolve against `GET /users`. Null when it was imported.", "type": "string" }, "created_at": { "type": "string", "description": "When the commission was recorded." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "status", "lender_id", "lender_name", "funded_amount", "finder_fee_bps", "finder_fee_amount", "bonus_bps", "bonus_amount", "buydown_amount", "buydown_reason", "gross_amount", "expected_payout_at", "paid_at", "clawback_amount", "clawback_at", "clawback_reason", "notes", "revision", "line_items", "splits", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A lender (INVALID_LENDER) or a split broker (INVALID_BROKER) is not in your brokerage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The API key's broker cannot see compensation on this deal (COMMISSION_ACCESS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The deal already has a commission (COMMISSION_EXISTS). Change it with PATCH.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealCommission", "summary": "Change a deal's commission", "description": "Changes the fields you send. `line_items` and `splits` replace the whole list when sent, and are left alone when omitted.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ], "description": "`pending` until the lender confirms, `paid` when the money arrived, `clawed_back` when it was taken back." }, "lender_id": { "description": "A lender in your list.", "nullable": true, "type": "string" }, "lender_name": { "description": "The paying lender's name.", "nullable": true, "type": "string", "maxLength": 255 }, "funded_amount": { "description": "Dollars funded.", "nullable": true, "type": "number" }, "finder_fee_bps": { "description": "Finder's fee in basis points.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "finder_fee_amount": { "description": "Finder's fee in dollars.", "nullable": true, "type": "number" }, "bonus_bps": { "description": "Volume bonus in basis points.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bonus_amount": { "description": "Volume bonus in dollars.", "nullable": true, "type": "number" }, "buydown_amount": { "description": "Buydown in dollars.", "nullable": true, "type": "number" }, "buydown_reason": { "description": "Why the rate was bought down.", "nullable": true, "type": "string", "maxLength": 1000 }, "gross_amount": { "description": "Gross in dollars. Ignored when line items exist: the gross is then their sum less the buydown.", "nullable": true, "type": "number" }, "expected_payout_at": { "description": "When the lender is expected to pay.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "paid_at": { "description": "When the lender paid.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "clawback_amount": { "description": "Dollars taken back.", "nullable": true, "type": "number" }, "clawback_at": { "description": "When.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "clawback_reason": { "description": "Why.", "nullable": true, "type": "string", "maxLength": 1000 }, "notes": { "description": "Free text.", "nullable": true, "type": "string", "maxLength": 2000 }, "line_items": { "description": "Replaces every line item when sent.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "finder_fee", "volume_bonus", "mpp", "other" ], "description": "Where the money comes from: the lender's finder's fee, a volume bonus, mortgage protection (`mpp`), or `other`." }, "label": { "description": "Your own label. Only kept with kind `other`.", "nullable": true, "type": "string", "maxLength": 120 }, "mpp_source": { "nullable": true, "description": "Only with kind `mpp`: paid through the lender, or direct by the insurer.", "type": "string", "enum": [ "lender_paid", "direct" ] }, "amount": { "type": "number", "minimum": 0, "description": "Dollars." }, "status": { "description": "Defaults to `expected`.", "type": "string", "enum": [ "expected", "invoiced", "received" ] }, "expected_at": { "description": "When the money is expected.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "received_at": { "description": "When it arrived.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "notes": { "description": "Free text.", "nullable": true, "type": "string", "maxLength": 1000 } }, "required": [ "kind", "amount" ], "additionalProperties": false } }, "splits": { "description": "Replaces every split when sent.", "type": "array", "items": { "type": "object", "properties": { "payee_type": { "description": "Defaults to `broker`.", "type": "string", "enum": [ "broker", "house", "franchise", "referral", "other" ] }, "broker_user_id": { "description": "With `broker`: a user in your brokerage.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 255 }, "payee_label": { "description": "With any other payee type: the party's name.", "nullable": true, "type": "string", "maxLength": 120 }, "share_percent": { "description": "Percent of the gross.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "share_amount": { "description": "Dollars, when the share is a fixed amount.", "nullable": true, "type": "number" }, "role": { "description": "Your own label for the payee's part.", "nullable": true, "type": "string", "maxLength": 100 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "commission", "description": "The type of this record. Always `commission`.", "type": "string", "enum": [ "commission" ] }, "id": { "type": "string", "description": "Stable identifier for the commission." }, "deal_id": { "type": "string", "description": "The deal. One commission per deal." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ], "description": "`pending` until the lender confirms, `paid` when the money arrived, `clawed_back` when it was taken back." }, "lender_id": { "nullable": true, "description": "The paying lender, when it is one of yours. Resolve against `GET /lenders`.", "type": "string" }, "lender_name": { "nullable": true, "description": "The paying lender's name, for a lender not in your list.", "type": "string" }, "funded_amount": { "nullable": true, "description": "Dollars funded, the basis for the finder's fee.", "type": "number" }, "finder_fee_bps": { "nullable": true, "description": "Finder's fee in basis points, as the broker typed it (85 is 0.85%).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "finder_fee_amount": { "nullable": true, "description": "Finder's fee in dollars. This figure is authoritative over the basis points.", "type": "number" }, "bonus_bps": { "nullable": true, "description": "Volume bonus in basis points.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bonus_amount": { "nullable": true, "description": "Volume bonus in dollars.", "type": "number" }, "buydown_amount": { "nullable": true, "description": "Dollars handed back to buy the rate down. `gross_amount` is already net of it.", "type": "number" }, "buydown_reason": { "nullable": true, "description": "The broker's note on why they bought the rate down.", "type": "string" }, "gross_amount": { "nullable": true, "description": "Dollars the brokerage earns before splits. The sum of the line items less the buydown, whenever line items exist.", "type": "number" }, "expected_payout_at": { "nullable": true, "description": "When the lender is expected to pay.", "type": "string" }, "paid_at": { "nullable": true, "description": "When the lender paid.", "type": "string" }, "clawback_amount": { "nullable": true, "description": "Dollars taken back, when the deal paid out early.", "type": "number" }, "clawback_at": { "nullable": true, "description": "When it was taken back.", "type": "string" }, "clawback_reason": { "nullable": true, "description": "Why.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments on every change to the money. What the accounting posting is keyed on." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_line", "description": "The type of this record. Always `commission_line`.", "type": "string", "enum": [ "commission_line" ] }, "id": { "type": "string", "description": "Stable identifier for the line." }, "kind": { "type": "string", "enum": [ "finder_fee", "volume_bonus", "mpp", "other" ], "description": "Where the money comes from: the lender's finder's fee, a volume bonus, mortgage protection (`mpp`), or `other`." }, "label": { "nullable": true, "description": "Your own label. Only with kind `other`.", "type": "string" }, "mpp_source": { "nullable": true, "description": "Only with kind `mpp`: paid through the lender, or direct by the insurer.", "type": "string", "enum": [ "lender_paid", "direct" ] }, "amount": { "type": "number", "description": "Dollars. What was or is expected to be paid on this line." }, "status": { "type": "string", "enum": [ "expected", "invoiced", "received" ], "description": "`expected` until invoiced, then `received` when the money arrived." }, "expected_at": { "nullable": true, "description": "When the money is expected.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived. Null until it did.", "type": "string" }, "notes": { "nullable": true, "description": "Free text.", "type": "string" }, "created_at": { "type": "string", "description": "When the line was added." }, "updated_at": { "type": "string", "description": "When the line last changed." } }, "required": [ "object", "id", "kind", "label", "mpp_source", "amount", "status", "expected_at", "received_at", "notes", "created_at", "updated_at" ], "additionalProperties": false }, "description": "What the deal pays, by source." }, "splits": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "commission_split", "description": "The type of this record. Always `commission_split`.", "type": "string", "enum": [ "commission_split" ] }, "id": { "type": "string", "description": "Stable identifier for the split." }, "payee_type": { "type": "string", "enum": [ "broker", "house", "franchise", "referral", "other" ], "description": "Who gets the share: one of your brokers, the house, a franchise, a referral partner, or another party." }, "broker_user_id": { "nullable": true, "description": "With `broker`: the user who gets the share. Resolve against `GET /users`.", "type": "string" }, "payee_label": { "nullable": true, "description": "With any other payee type: the party's name.", "type": "string" }, "share_percent": { "nullable": true, "description": "Percent of the parent pool. Of the gross at the top level.", "type": "number" }, "share_amount": { "nullable": true, "description": "Dollars, when the share is a fixed amount.", "type": "number" }, "role": { "nullable": true, "description": "Your own label for the payee's part in the deal.", "type": "string" }, "parent_split_id": { "nullable": true, "description": "The split this one carves out of, when a brokerage divides its own share. Null at the top level.", "type": "string" }, "created_at": { "type": "string", "description": "When the split was added." } }, "required": [ "object", "id", "payee_type", "broker_user_id", "payee_label", "share_percent", "share_amount", "role", "parent_split_id", "created_at" ], "additionalProperties": false }, "description": "How the gross is allocated. An allocation is not a payment." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded the commission. Resolve against `GET /users`. Null when it was imported.", "type": "string" }, "created_at": { "type": "string", "description": "When the commission was recorded." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "status", "lender_id", "lender_name", "funded_amount", "finder_fee_bps", "finder_fee_amount", "bonus_bps", "bonus_amount", "buydown_amount", "buydown_reason", "gross_amount", "expected_payout_at", "paid_at", "clawback_amount", "clawback_at", "clawback_reason", "notes", "revision", "line_items", "splits", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A lender (INVALID_LENDER) or a split broker (INVALID_BROKER) is not in your brokerage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The API key's broker cannot see compensation on this deal (COMMISSION_ACCESS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not found, or it has no commission yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealCommission", "summary": "Remove a deal's commission", "description": "Removes the commission with its line items and splits.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The API key's broker cannot see compensation on this deal (COMMISSION_ACCESS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not found, or it has no commission (NO_COMMISSION).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consents": { "get": { "operationId": "listDealConsents", "summary": "List the consents on a deal", "description": "Every consent recorded on the deal, newest first, including revoked and expired ones. `is_active` says which still stand.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "consent", "description": "The type of this record. Always `consent`.", "type": "string", "enum": [ "consent" ] }, "id": { "type": "string", "description": "Stable identifier for the consent." }, "deal_id": { "type": "string", "description": "The deal it was given on." }, "contact_id": { "type": "string", "description": "The party who gave it. Resolve against `GET /contacts/{id}`." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What was authorized: a credit pull, a lender submission, privacy processing, electronic delivery, or a mortgage protection plan transfer." }, "method": { "type": "string", "description": "How it was obtained: `verbal`, `written`, `e_sign`, `portal`, or `other`." }, "granted_by_user_id": { "nullable": true, "description": "The broker who recorded it. Null when the client gave it themselves.", "type": "string" }, "granted_at": { "type": "string", "description": "When it was given." }, "expires_at": { "nullable": true, "description": "When it lapses. Null if it does not.", "type": "string" }, "revoked_at": { "nullable": true, "description": "When it was revoked. Null while it stands.", "type": "string" }, "revoked_by_user_id": { "nullable": true, "description": "Who revoked it.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on how it was obtained.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the consent is neither revoked nor expired." }, "text": { "nullable": true, "description": "The exact wording the client agreed to, as it read at the moment they agreed. Null when the consent was recorded without one, e.g. a verbal consent a broker logged.", "type": "string" }, "text_version": { "nullable": true, "description": "Which version of the consent wording `text` is. Null with no wording.", "type": "string" }, "locale": { "nullable": true, "description": "The language the wording was shown in, e.g. `en` or `fr`.", "type": "string" }, "created_at": { "type": "string", "description": "When the consent was recorded in BrokerPlus. `granted_at` is when it was given." }, "updated_at": { "type": "string", "description": "Last change, e.g. a revocation." } }, "required": [ "object", "id", "deal_id", "contact_id", "scope", "method", "granted_by_user_id", "granted_at", "expires_at", "revoked_at", "revoked_by_user_id", "note", "is_active", "text", "text_version", "locale", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "recordDealConsent", "summary": "Record a consent on a deal", "description": "Records that a party on the deal authorized a scope, and how. The consent is attributed to the broker your key acts as. Recording one does not run anything: a credit pull or submission still happens in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A party on this deal." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What is being authorized." }, "method": { "type": "string", "enum": [ "verbal", "written", "e_sign", "portal", "other" ], "description": "How it was obtained." }, "expires_at": { "description": "When it lapses. Omit for no expiry. A `credit_pull` consent always lapses 30 days after it is given; an earlier date is kept, a later one is cut to 30 days.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "note": { "description": "How it was obtained, in your own words.", "nullable": true, "type": "string", "maxLength": 2000 } }, "required": [ "contact_id", "scope", "method" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consent", "description": "The type of this record. Always `consent`.", "type": "string", "enum": [ "consent" ] }, "id": { "type": "string", "description": "Stable identifier for the consent." }, "deal_id": { "type": "string", "description": "The deal it was given on." }, "contact_id": { "type": "string", "description": "The party who gave it. Resolve against `GET /contacts/{id}`." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What was authorized: a credit pull, a lender submission, privacy processing, electronic delivery, or a mortgage protection plan transfer." }, "method": { "type": "string", "description": "How it was obtained: `verbal`, `written`, `e_sign`, `portal`, or `other`." }, "granted_by_user_id": { "nullable": true, "description": "The broker who recorded it. Null when the client gave it themselves.", "type": "string" }, "granted_at": { "type": "string", "description": "When it was given." }, "expires_at": { "nullable": true, "description": "When it lapses. Null if it does not.", "type": "string" }, "revoked_at": { "nullable": true, "description": "When it was revoked. Null while it stands.", "type": "string" }, "revoked_by_user_id": { "nullable": true, "description": "Who revoked it.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on how it was obtained.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the consent is neither revoked nor expired." }, "text": { "nullable": true, "description": "The exact wording the client agreed to, as it read at the moment they agreed. Null when the consent was recorded without one, e.g. a verbal consent a broker logged.", "type": "string" }, "text_version": { "nullable": true, "description": "Which version of the consent wording `text` is. Null with no wording.", "type": "string" }, "locale": { "nullable": true, "description": "The language the wording was shown in, e.g. `en` or `fr`.", "type": "string" }, "created_at": { "type": "string", "description": "When the consent was recorded in BrokerPlus. `granted_at` is when it was given." }, "updated_at": { "type": "string", "description": "Last change, e.g. a revocation." } }, "required": [ "object", "id", "deal_id", "contact_id", "scope", "method", "granted_by_user_id", "granted_at", "expires_at", "revoked_at", "revoked_by_user_id", "note", "is_active", "text", "text_version", "locale", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not found, or the contact is not a party on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consents/{consentId}/revoke": { "post": { "operationId": "revokeDealConsent", "summary": "Revoke a consent", "description": "Stamps the consent revoked. The row stays on the file.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "consentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consent", "description": "The type of this record. Always `consent`.", "type": "string", "enum": [ "consent" ] }, "id": { "type": "string", "description": "Stable identifier for the consent." }, "deal_id": { "type": "string", "description": "The deal it was given on." }, "contact_id": { "type": "string", "description": "The party who gave it. Resolve against `GET /contacts/{id}`." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What was authorized: a credit pull, a lender submission, privacy processing, electronic delivery, or a mortgage protection plan transfer." }, "method": { "type": "string", "description": "How it was obtained: `verbal`, `written`, `e_sign`, `portal`, or `other`." }, "granted_by_user_id": { "nullable": true, "description": "The broker who recorded it. Null when the client gave it themselves.", "type": "string" }, "granted_at": { "type": "string", "description": "When it was given." }, "expires_at": { "nullable": true, "description": "When it lapses. Null if it does not.", "type": "string" }, "revoked_at": { "nullable": true, "description": "When it was revoked. Null while it stands.", "type": "string" }, "revoked_by_user_id": { "nullable": true, "description": "Who revoked it.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on how it was obtained.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the consent is neither revoked nor expired." }, "text": { "nullable": true, "description": "The exact wording the client agreed to, as it read at the moment they agreed. Null when the consent was recorded without one, e.g. a verbal consent a broker logged.", "type": "string" }, "text_version": { "nullable": true, "description": "Which version of the consent wording `text` is. Null with no wording.", "type": "string" }, "locale": { "nullable": true, "description": "The language the wording was shown in, e.g. `en` or `fr`.", "type": "string" }, "created_at": { "type": "string", "description": "When the consent was recorded in BrokerPlus. `granted_at` is when it was given." }, "updated_at": { "type": "string", "description": "Last change, e.g. a revocation." } }, "required": [ "object", "id", "deal_id", "contact_id", "scope", "method", "granted_by_user_id", "granted_at", "expires_at", "revoked_at", "revoked_by_user_id", "note", "is_active", "text", "text_version", "locale", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The consent is already revoked (ALREADY_REVOKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consent-forms": { "get": { "operationId": "listDealConsentForms", "summary": "List the consent forms on a deal", "description": "The consent forms emailed to the borrowers on the deal, newest first. A borrower signs a form by typing their name, and the signature records a consent on the deal in `consent_id`. A form has no `updated_at`, so this list takes no `updated_since`: filter by `status` to find the forms that came back. A credit consent sent on the brokerage's own uploaded form is a signing request, not a form, and is not listed.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the forms sent to this borrower." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ] }, "description": "Only the forms that ask for this consent." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ] }, "description": "Only the forms with this status." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "consent_form", "description": "The type of this record. Always `consent_form`.", "type": "string", "enum": [ "consent_form" ] }, "id": { "type": "string", "description": "Stable identifier for the form." }, "deal_id": { "type": "string", "description": "The deal the consent is for." }, "contact_id": { "type": "string", "description": "The borrower the form was sent to." }, "client_name": { "type": "string", "description": "The borrower's name as it was when the form was sent." }, "email": { "type": "string", "description": "The address the form was sent to." }, "broker_id": { "type": "string", "description": "The broker the form came from." }, "broker_name": { "type": "string", "description": "The name of that broker as it was when the form was sent." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What the borrower is asked to authorize." }, "status": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ], "description": "`sent`: emailed and not opened. `viewed`: the borrower opened it. `submitted`: the borrower signed it, and the consent is on the deal. `expired`: the link closed before a signature." }, "text": { "type": "string", "description": "The words the borrower is asked to agree to, as they were when the form was sent." }, "text_version": { "type": "string", "description": "The version of those words." }, "signature_name": { "nullable": true, "description": "The name the borrower typed to sign. Null until the borrower signs.", "type": "string" }, "consent_id": { "nullable": true, "description": "The consent that the signature recorded on the deal. Read it with `GET /v1/deals/{id}/consents`. Null until the borrower signs.", "type": "string" }, "sent_at": { "type": "string", "description": "When the form was sent." }, "viewed_at": { "nullable": true, "description": "When the borrower first opened it. Null if never.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the borrower signed it. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking a signature." } }, "required": [ "object", "id", "deal_id", "contact_id", "client_name", "email", "broker_id", "broker_name", "scope", "status", "text", "text_version", "signature_name", "consent_id", "sent_at", "viewed_at", "submitted_at", "expires_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "sendDealConsentForm", "summary": "Send a consent form", "description": "Emails a borrower on the deal a form to sign their consent for one scope, as the deal's Compliance tab does. The email goes out now, from the broker's connected email, with a link that works for 30 days. For `credit_pull`, when the brokerage uploaded its own credit consent form, the borrower gets that form to sign in an intake instead, and `kind` is `intake`. A key with the `no_sending` limit cannot use this endpoint. Supports `Idempotency-Key`.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The borrower to ask. The borrower must be on the deal." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What to ask the borrower to authorize. For `credit_pull`, when the brokerage uploaded its own credit consent form in BrokerPlus, the borrower gets that form to sign instead, as in BrokerPlus." }, "email": { "description": "The address to send it to. When it differs from the borrower's email, it replaces that email, as in BrokerPlus.", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "message": { "description": "A note from the broker in the email. 2000 characters at most.", "type": "string", "maxLength": 2000 } }, "required": [ "contact_id", "scope" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consent_request", "description": "The type of this record. Always `consent_request`.", "type": "string", "enum": [ "consent_request" ] }, "id": { "type": "string", "description": "The record that was sent. For `consent_form`, read it with `GET /v1/deals/{id}/consent-forms/{formId}`. For `intake`, read it with `GET /v1/intakes/{id}`." }, "kind": { "type": "string", "enum": [ "consent_form", "intake" ], "description": "`consent_form`: the borrower got the BrokerPlus consent form. `intake`: the borrower got the brokerage's own credit consent form to sign, in an intake." }, "deal_id": { "type": "string", "description": "The deal the consent is for." }, "contact_id": { "type": "string", "description": "The borrower the request was sent to." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What the borrower is asked to authorize." } }, "required": [ "object", "id", "kind", "deal_id", "contact_id", "scope" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The borrower has no email address and you sent no `email` (NO_EMAIL).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot change it, or the contact is not on the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker has no email connected (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "The email could not be sent (EMAIL_NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consent-forms/{formId}": { "get": { "operationId": "getDealConsentForm", "summary": "Retrieve a consent form", "description": "One consent form on the deal: who it went to, the words it asks the borrower to agree to, and its status.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consent_form", "description": "The type of this record. Always `consent_form`.", "type": "string", "enum": [ "consent_form" ] }, "id": { "type": "string", "description": "Stable identifier for the form." }, "deal_id": { "type": "string", "description": "The deal the consent is for." }, "contact_id": { "type": "string", "description": "The borrower the form was sent to." }, "client_name": { "type": "string", "description": "The borrower's name as it was when the form was sent." }, "email": { "type": "string", "description": "The address the form was sent to." }, "broker_id": { "type": "string", "description": "The broker the form came from." }, "broker_name": { "type": "string", "description": "The name of that broker as it was when the form was sent." }, "scope": { "type": "string", "enum": [ "credit_pull", "lender_submission", "privacy_processing", "e_delivery", "mpp_transfer" ], "description": "What the borrower is asked to authorize." }, "status": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ], "description": "`sent`: emailed and not opened. `viewed`: the borrower opened it. `submitted`: the borrower signed it, and the consent is on the deal. `expired`: the link closed before a signature." }, "text": { "type": "string", "description": "The words the borrower is asked to agree to, as they were when the form was sent." }, "text_version": { "type": "string", "description": "The version of those words." }, "signature_name": { "nullable": true, "description": "The name the borrower typed to sign. Null until the borrower signs.", "type": "string" }, "consent_id": { "nullable": true, "description": "The consent that the signature recorded on the deal. Read it with `GET /v1/deals/{id}/consents`. Null until the borrower signs.", "type": "string" }, "sent_at": { "type": "string", "description": "When the form was sent." }, "viewed_at": { "nullable": true, "description": "When the borrower first opened it. Null if never.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the borrower signed it. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking a signature." } }, "required": [ "object", "id", "deal_id", "contact_id", "client_name", "email", "broker_id", "broker_name", "scope", "status", "text", "text_version", "signature_name", "consent_id", "sent_at", "viewed_at", "submitted_at", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/stage-history": { "get": { "operationId": "listDealStageHistory", "summary": "List a deal's stage history", "description": "Every stage move recorded on the deal, newest first. BrokerPlus records a move whenever the deal changes stage in the dashboard, through the API, or by automation. Imported deals carry history only from their import date onward.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "stage_transition", "description": "The type of this record. Always `stage_transition`.", "type": "string", "enum": [ "stage_transition" ] }, "id": { "type": "string", "description": "Stable identifier for the transition." }, "from_stage": { "nullable": true, "description": "Where the deal was. Null when the deal had no stage, or on its first placement.", "type": "object", "properties": { "id": { "type": "string", "description": "The stage's id at the time. Resolves against the pipeline's stages unless the stage was archived since." }, "key": { "type": "string", "description": "The stage's machine-readable key at the time." }, "label": { "type": "string", "description": "The stage's display name at the time." } }, "required": [ "id", "key", "label" ], "additionalProperties": false }, "to_stage": { "type": "object", "properties": { "id": { "type": "string", "description": "The stage's id at the time. Resolves against the pipeline's stages unless the stage was archived since." }, "key": { "type": "string", "description": "The stage's machine-readable key at the time." }, "label": { "type": "string", "description": "The stage's display name at the time." } }, "required": [ "id", "key", "label" ], "additionalProperties": false, "description": "Where the deal went." }, "actor_type": { "type": "string", "enum": [ "broker", "agent", "borrower", "system", "lender" ], "description": "Who moved it: a broker in BrokerPlus or through the API, BrokerPlus itself (`agent`, `system`), a borrower, or a lender response." }, "actor_id": { "nullable": true, "description": "The user who moved it, when a broker did. Resolves against `GET /users/{id}`.", "type": "string" }, "reason": { "nullable": true, "description": "Free text recorded with the move, if any.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the deal entered `to_stage`." } }, "required": [ "object", "id", "from_stage", "to_stage", "actor_type", "actor_id", "reason", "occurred_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes": { "get": { "operationId": "listDealNotes", "summary": "List notes on a deal", "description": "Pinned first, then newest.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealNote", "summary": "Add a note to a deal", "description": "The note is attributed to the broker your key acts as.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." }, "pinned": { "description": "Defaults to `false`.", "type": "boolean" }, "parent_id": { "description": "Reply to this note. Must belong to the same record, and cannot itself be a reply.", "nullable": true, "type": "string" }, "type": { "description": "The kind of note, as a `slug` from `GET /v1/note-types` for the same scope (deal or contact). Defaults to `general`. A reply always has the kind of its parent, so this is ignored on a reply.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes/{noteId}": { "patch": { "operationId": "updateDealNote", "summary": "Update a note on a deal", "description": "Edit the words, pin or unpin the note, or change its kind. Only the fields you send change. A teammate newly named with a mention gets a notification, as in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "description": "The new note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content.", "type": "string", "minLength": 1, "maxLength": 20000 }, "pinned": { "description": "`true` pins the note to the top of the record. A pin does not change `updated_at`.", "type": "boolean" }, "type": { "description": "Change the kind of note, for example `underwriting`. The brokerage must have this kind. A reply always has the kind of its parent, so you cannot change it on a reply.", "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note", "description": "The type of this record. Always `note`.", "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The teammate the note names. Resolve against `GET /v1/users/{id}`." }, "user_name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "user_id", "user_name" ], "additionalProperties": false }, "description": "The teammates the note names. Each one got a notification. A name in the body of a teammate who cannot see the record is not here." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false }, "description": "The emoji reactions on the note, in the order they were first added." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false }, "description": "The files attached to the note, oldest first." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "type": { "type": "string", "description": "The kind of note, as the brokerage files it, e.g. `general`, `underwriting` or `call` - or a kind the team added. The kinds are listed by `GET /v1/note-types`." }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "body", "mentions", "reactions", "attachments", "pinned", "author_id", "author_name", "parent_id", "type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealNote", "summary": "Delete a note from a deal", "description": "Deletes the note and its replies. You cannot undo this. Any teammate who can edit the deal can delete its notes, as in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes/mentionable": { "get": { "operationId": "listDealNoteMentionables", "summary": "List who a deal note can mention", "description": "The teammates on the deal's team, by name. To mention one in a note, put `@Name` in the body. The teammate gets a notification, as in BrokerPlus. A mention of somebody who is not in this list is kept as text, and nobody gets a notification.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "user", "description": "The type of this record. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "The teammate's user id. Put it in a mention in a note body." }, "name": { "nullable": true, "description": "The teammate's name. Null if the teammate has no name on file.", "type": "string" } }, "required": [ "object", "id", "name" ], "additionalProperties": false }, "description": "The teammates a deal note can mention." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes/{noteId}/reactions": { "post": { "operationId": "reactDealNote", "summary": "React to a deal note", "description": "Adds or takes off one emoji reaction of the broker your key acts as. Sending the same reaction again changes nothing. A reaction also marks a mention of that broker in the note as seen.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "minLength": 1, "maxLength": 32, "description": "One emoji, for example `👍`." }, "active": { "type": "boolean", "description": "`true` adds the reaction of the broker your key acts as. `false` takes it off." } }, "required": [ "emoji", "active" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "emoji": { "type": "string", "description": "The emoji, for example `👍`." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many teammates reacted with this emoji." }, "reacted_by_me": { "type": "boolean", "description": "True when the broker your key acts as reacted with this emoji." } }, "required": [ "emoji", "count", "reacted_by_me" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`emoji` is not one emoji (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes/{noteId}/attachments": { "post": { "operationId": "attachDealNoteFile", "summary": "Attach a PDF to a deal note", "description": "Send the file as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. The file must be a PDF of at most 25 MB. BrokerPlus checks the content, not the name. The response does not include a link: get one with the file's `id`.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "The PDF, at most 25 MB. Its file name is the name that BrokerPlus shows." } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file name that BrokerPlus shows. `.pdf` is added when it is not there." }, "content_base64": { "type": "string", "minLength": 1, "description": "The file, in standard base64. It must be a PDF of at most 25 MB. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing or empty (NO_FILE), is not a PDF (INVALID_TYPE), is larger than 25 MB (FILE_TOO_LARGE), or the base64 is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/notes/{noteId}/attachments/{attachmentId}": { "get": { "operationId": "getDealNoteFile", "summary": "Get a link to a file on a deal note", "description": "A signed link to the PDF, valid for five minutes.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_attachment", "description": "The type of this record. Always `note_attachment`.", "type": "string", "enum": [ "note_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the file. Use it to get a download link." }, "name": { "type": "string", "description": "The file name." }, "content_type": { "type": "string", "description": "The MIME type. Always `application/pdf` today." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "uploaded_by_id": { "type": "string", "description": "The broker who attached the file." }, "created_at": { "type": "string", "description": "When the file was attached." }, "download_url": { "type": "string", "description": "A link to the file. It carries its own authorization, so do not store it." }, "download_url_expires_at": { "type": "string", "description": "When the link stops working, five minutes after you asked for it." } }, "required": [ "object", "id", "name", "content_type", "size", "uploaded_by_id", "created_at", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/documents": { "get": { "operationId": "listDealDocuments", "summary": "List a deal's documents", "description": "Metadata only, newest first. Fetch a single document to get a download URL - minting one per row here would issue links nobody follows.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "document_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only documents of this type, a code from `GET /v1/document-types`." }, { "name": "verified", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Send `true` for verified documents only, or `false` for documents not yet verified." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the documents of this borrower." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "document", "description": "The type of this record. Always `document`.", "type": "string", "enum": [ "document" ] }, "id": { "type": "string", "description": "Stable identifier for the document." }, "deal_id": { "type": "string", "description": "The deal this document is filed under." }, "contact_id": { "nullable": true, "description": "The borrower it belongs to, when the file names one.", "type": "string" }, "contact_name": { "nullable": true, "description": "The full name of that borrower, for display. Null when `contact_id` is null.", "type": "string" }, "file_name": { "type": "string", "description": "Original filename as uploaded." }, "display_name": { "nullable": true, "description": "The name brokers see in BrokerPlus. A broker can type it, or BrokerPlus makes it from the document type. Null until either occurs.", "type": "string" }, "file_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs. `GET /v1/document-types` lists the codes." }, "document_type_label": { "nullable": true, "description": "The readable name of `document_type`, e.g. `Paystub`. Null for `unknown` and for a custom type.", "type": "string" }, "classification_status": { "type": "string", "description": "`pending`, `classified`, or `needs_review`. New values can appear as the classifier grows." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "Where the document is on the deal's document board. `pending` and `review` both mean received and not yet checked. `verified` means checked and ready to go to a lender." }, "verified": { "type": "boolean", "description": "`true` when `stage` is `verified`. Filter the list with `verified=true`." }, "folder": { "nullable": true, "description": "The folder of a verified document, e.g. `income` or `down_payment`. `unsorted` means a broker has not filed it yet. Null when the document is not verified.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] }, "uploaded_via": { "type": "string", "enum": [ "portal", "email", "manual", "api", "assembled", "generated" ], "description": "How it arrived: `manual` (a broker), `api` (this API), `email` (an email attachment), `portal` (the client), `generated` or `assembled` (made in BrokerPlus)." }, "uploaded_by_user_id": { "nullable": true, "description": "The broker who added the file. Null when the client, an email, or BrokerPlus added it.", "type": "string" }, "uploaded_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments when a document is replaced rather than added." }, "excluded_from_submission": { "type": "boolean", "description": "True when the broker has marked the file as one that does not go to a lender, e.g. a duplicate or a working copy. A new lender submission leaves it out unless the broker picks it." }, "created_at": { "type": "string", "description": "When the document was uploaded." }, "updated_at": { "type": "string", "description": "Last change to its metadata or classification." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "file_name", "display_name", "file_type", "file_size", "document_type", "document_type_label", "classification_status", "stage", "verified", "folder", "uploaded_via", "uploaded_by_user_id", "uploaded_by_name", "version", "excluded_from_submission", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` is not a date, or `verified` is not `true` or `false` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "uploadDealDocument", "summary": "Upload a document to a deal", "description": "Send the file as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. BrokerPlus stores the file, classifies it, and checks it, the same as a file a broker uploads. The document starts with `classification_status` `pending`. The upload fires the `document.uploaded` webhook.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file. 50 MB maximum. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." }, "document_type": { "description": "What the file is, as a code from `GET /v1/document-types`. BrokerPlus uses it as the expected type when it checks the file. Leave it out and BrokerPlus classifies the file.", "type": "string", "minLength": 1, "maxLength": 100 }, "contact_id": { "description": "The borrower the file belongs to. Must be an applicant on this deal, not a partner.", "type": "string" }, "name": { "description": "The name brokers see. Leave it out and BrokerPlus names the file from its type.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `paystub.pdf`." }, "content_type": { "type": "string", "minLength": 1, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding. Send a larger file as `multipart/form-data`." }, "document_type": { "description": "What the file is, as a code from `GET /v1/document-types`. BrokerPlus uses it as the expected type when it checks the file. Leave it out and BrokerPlus classifies the file.", "type": "string", "minLength": 1, "maxLength": 100 }, "contact_id": { "description": "The borrower the file belongs to. Must be an applicant on this deal, not a partner.", "type": "string" }, "name": { "description": "The name brokers see. Leave it out and BrokerPlus names the file from its type.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document", "description": "The type of this record. Always `document`.", "type": "string", "enum": [ "document" ] }, "id": { "type": "string", "description": "Stable identifier for the document." }, "deal_id": { "type": "string", "description": "The deal this document is filed under." }, "contact_id": { "nullable": true, "description": "The borrower it belongs to, when the file names one.", "type": "string" }, "contact_name": { "nullable": true, "description": "The full name of that borrower, for display. Null when `contact_id` is null.", "type": "string" }, "file_name": { "type": "string", "description": "Original filename as uploaded." }, "display_name": { "nullable": true, "description": "The name brokers see in BrokerPlus. A broker can type it, or BrokerPlus makes it from the document type. Null until either occurs.", "type": "string" }, "file_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs. `GET /v1/document-types` lists the codes." }, "document_type_label": { "nullable": true, "description": "The readable name of `document_type`, e.g. `Paystub`. Null for `unknown` and for a custom type.", "type": "string" }, "classification_status": { "type": "string", "description": "`pending`, `classified`, or `needs_review`. New values can appear as the classifier grows." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "Where the document is on the deal's document board. `pending` and `review` both mean received and not yet checked. `verified` means checked and ready to go to a lender." }, "verified": { "type": "boolean", "description": "`true` when `stage` is `verified`. Filter the list with `verified=true`." }, "folder": { "nullable": true, "description": "The folder of a verified document, e.g. `income` or `down_payment`. `unsorted` means a broker has not filed it yet. Null when the document is not verified.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] }, "uploaded_via": { "type": "string", "enum": [ "portal", "email", "manual", "api", "assembled", "generated" ], "description": "How it arrived: `manual` (a broker), `api` (this API), `email` (an email attachment), `portal` (the client), `generated` or `assembled` (made in BrokerPlus)." }, "uploaded_by_user_id": { "nullable": true, "description": "The broker who added the file. Null when the client, an email, or BrokerPlus added it.", "type": "string" }, "uploaded_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments when a document is replaced rather than added." }, "excluded_from_submission": { "type": "boolean", "description": "True when the broker has marked the file as one that does not go to a lender, e.g. a duplicate or a working copy. A new lender submission leaves it out unless the broker picks it." }, "created_at": { "type": "string", "description": "When the document was uploaded." }, "updated_at": { "type": "string", "description": "Last change to its metadata or classification." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "file_name", "display_name", "file_type", "file_size", "document_type", "document_type_label", "classification_status", "stage", "verified", "folder", "uploaded_via", "uploaded_by_user_id", "uploaded_by_name", "version", "excluded_from_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing, its type is not allowed, or its content does not match its type (VALIDATION_ERROR). `document_type` is not a known code (INVALID_DOCUMENT_TYPE). `contact_id` is not an applicant on this deal (NOT_AN_APPLICANT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "The file is larger than the limit for its encoding (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The PDF is not readable (INVALID_PDF), or it has a password (LOCKED_PDF).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/document-requests": { "get": { "operationId": "listDealDocumentRequests", "summary": "List the documents a client still owes", "description": "Every document that BrokerPlus asked a client for on this deal and that the client has not sent, one row for each applicant who owes it. Newest request first.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "document_request", "description": "The type of this record. Always `document_request`.", "type": "string", "enum": [ "document_request" ] }, "id": { "type": "string", "description": "Stable identifier for this request to this applicant." }, "label": { "type": "string", "description": "What the client was asked for, in the words they saw." }, "document_type": { "nullable": true, "description": "The document type asked for, from `GET /v1/document-types`. Null when the request names no type.", "type": "string" }, "required": { "type": "boolean", "description": "`true` when the client must send it. `false` for an optional request." }, "contact_id": { "type": "string", "description": "The applicant who owes the document." }, "contact_name": { "type": "string", "description": "That applicant's full name, for display." }, "is_primary_applicant": { "type": "boolean", "description": "`true` for the main applicant, `false` for a co-applicant." }, "rejected": { "type": "boolean", "description": "`true` when the client sent a file and BrokerPlus or the broker refused it, so the request is open again." }, "waiting_on_intake": { "type": "boolean", "description": "`true` when the client has not seen the request yet, because it waits until they finish their application." }, "requested_at": { "type": "string", "description": "When the request was made." } }, "required": [ "object", "id", "label", "document_type", "required", "contact_id", "contact_name", "is_primary_applicant", "rejected", "waiting_on_intake", "requested_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "requestDealDocuments", "summary": "Ask the client for documents", "description": "Requests documents from the client now, as the Request Documents window in BrokerPlus does. The documents are added to the client's portal, and each applicant that a document is for gets an email with their link. The response is `201` with the document requests that this call added. To ask for the documents on a request template, send its `template_id`: each document goes to the applicants the template names. The deal must have a client portal: the client must have sent their intake back. A key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`: a retry with the same key gets the first response and emails nobody again.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "description": "The documents to ask for, from 1 to 50 with the documents of `template_id`. Send `documents`, `template_id`, or both.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "document_type": { "type": "string", "minLength": 1, "description": "The document to ask for. Use a `code` from `GET /v1/document-types`." }, "label": { "description": "What the client reads as the name of the request. The default is the label of the document type.", "type": "string", "minLength": 1, "maxLength": 300 }, "note": { "description": "A line under the request that tells the client what to send, for example `The last two months`.", "type": "string", "maxLength": 1000 }, "contact_id": { "description": "The applicant who must send it. The contact must be an applicant on the client's portal. Leave it out to ask every applicant.", "type": "string" }, "required": { "description": "`true` (the default) when the client must send it. `false` for an optional request.", "type": "boolean" } }, "required": [ "document_type" ], "additionalProperties": false } }, "template_id": { "description": "A request template from `GET /v1/request-templates`. Its documents are asked for as the template has them. The template must ask only for documents: send a template with questions or forms from BrokerPlus.", "type": "string", "minLength": 1 }, "message": { "description": "A note to the client. It is in the email and on the client's portal.", "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "document_request", "description": "The type of this record. Always `document_request`.", "type": "string", "enum": [ "document_request" ] }, "id": { "type": "string", "description": "Stable identifier for this request to this applicant." }, "label": { "type": "string", "description": "What the client was asked for, in the words they saw." }, "document_type": { "nullable": true, "description": "The document type asked for, from `GET /v1/document-types`. Null when the request names no type.", "type": "string" }, "required": { "type": "boolean", "description": "`true` when the client must send it. `false` for an optional request." }, "contact_id": { "type": "string", "description": "The applicant who owes the document." }, "contact_name": { "type": "string", "description": "That applicant's full name, for display." }, "is_primary_applicant": { "type": "boolean", "description": "`true` for the main applicant, `false` for a co-applicant." }, "rejected": { "type": "boolean", "description": "`true` when the client sent a file and BrokerPlus or the broker refused it, so the request is open again." }, "waiting_on_intake": { "type": "boolean", "description": "`true` when the client has not seen the request yet, because it waits until they finish their application." }, "requested_at": { "type": "string", "description": "When the request was made." } }, "required": [ "object", "id", "label", "document_type", "required", "contact_id", "contact_name", "is_primary_applicant", "rejected", "waiting_on_intake", "requested_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not there, or `template_id` is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The client has not sent their intake back, so there is no portal to add documents to (NO_CLIENT_HUB). Or the portal refused the request, and nothing was sent (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "A `document_type` is not a code from `GET /v1/document-types`, or a `contact_id` is not an applicant on the client's portal (VALIDATION_ERROR). `details.fields` names each one. The template asks for something other than documents (TEMPLATE_NOT_SENDABLE), or there is nothing to ask for (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package": { "get": { "operationId": "getDealFundingPackage", "summary": "Retrieve a deal's funding package", "description": "The lender's funding documents that the broker is preparing on this deal: each document, the person who signs it, and its form fields with the values that BrokerPlus writes in. Only the open package (`draft`) is returned. To send it for signature, use `POST /v1/deals/{id}/funding-package/send`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "funding_package", "description": "The type of this record. Always `funding_package`.", "type": "string", "enum": [ "funding_package" ] }, "id": { "type": "string", "description": "Stable identifier for the funding package." }, "deal_id": { "type": "string", "description": "The deal." }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "voided" ], "description": "`draft`: the broker is still adding documents and checking fields. `sent`, `completed` and `voided` follow the signing of a package that the broker sent from BrokerPlus." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "funding_package_item", "description": "The type of this record. Always `funding_package_item`.", "type": "string", "enum": [ "funding_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "package_id": { "type": "string", "description": "The funding package that holds the item." }, "document_id": { "type": "string", "description": "The document on the deal. Read it with `GET /v1/documents/{id}`." }, "document_name": { "type": "string", "description": "The file name of the document, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package. The first item is 0." }, "recipient_role": { "nullable": true, "description": "The part in the deal of the person who signs the document. Null until it is set.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "nullable": true, "description": "The person who signs the document. Always a participant on the deal. Null until it is set.", "type": "string" }, "recipient_name": { "nullable": true, "description": "The name of the person who signs the document, for display.", "type": "string" }, "has_form_fields": { "type": "boolean", "description": "True when the PDF has form fields that BrokerPlus read. False for a flat PDF: place its fields with `fields`." }, "page_count": { "nullable": true, "description": "The number of pages. Null when the file is not a readable PDF.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the form field in the PDF. It identifies the field in the document." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "nullable": true, "description": "A readable name for the field. Null until the fields are mapped.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "nullable": true, "description": "The deal value that fills the field, as a `key` from `GET /v1/deals/{id}/funding-package/context`. Null when the signer fills it or no value matched.", "type": "string" }, "value": { "nullable": true, "description": "The text that BrokerPlus writes into the field. Only set when `party` is `broker`.", "type": "string" }, "confidence": { "nullable": true, "description": "How sure the mapping is, from 0 to 1. A low value means the broker should check the field.", "type": "number" }, "reviewed": { "type": "boolean", "description": "True when a person confirmed the field." }, "prefilled": { "nullable": true, "description": "The text that the uploaded PDF already had in the field. Null if none.", "type": "string" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "label", "party", "source_key", "value", "confidence", "reviewed", "prefilled" ], "additionalProperties": false }, "description": "The form fields of the document, with who fills each and its value." }, "state": { "type": "string", "enum": [ "pending", "mapped", "reviewed" ], "description": "`pending`: the fields are read but not mapped. `mapped`: BrokerPlus proposed a value for each field. `reviewed`: a person confirmed the fields. Only a `reviewed` item can be sent." }, "created_at": { "type": "string", "description": "When the document was added to the package." }, "updated_at": { "type": "string", "description": "Last change to the item." } }, "required": [ "object", "id", "package_id", "document_id", "document_name", "position", "recipient_role", "recipient_contact_id", "recipient_name", "has_form_fields", "page_count", "fields", "state", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the package was started." }, "updated_at": { "type": "string", "description": "Last change to the package." } }, "required": [ "object", "id", "deal_id", "status", "items", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or it has no open funding package (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/context": { "get": { "operationId": "getDealFundingContext", "summary": "List the values a funding form can use", "description": "Every value that BrokerPlus holds on this deal and can write into a funding form: borrowers, the lawyer, the broker, and the reviewed commitment terms. Use a `key` as a field's `source_key`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The value to send as a field's `source_key`, for example `borrower.1.fullName`." }, "label": { "type": "string", "description": "A readable name for the value." }, "value": { "type": "string", "description": "The value that BrokerPlus writes into a field that names this key." } }, "required": [ "key", "label", "value" ], "additionalProperties": false }, "description": "The values, each with the key that a field names." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/items": { "post": { "operationId": "addDealFundingPackageItems", "summary": "Add documents to the funding package", "description": "Adds documents that are already on the deal to its open funding package, and starts a package if there is none. BrokerPlus reads the form fields of each PDF as it is added. A document already in the package is not added again, so a retry is safe.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Documents already on the deal, at most 20. A document that is already in the package is not added again." } }, "required": [ "document_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "funding_package", "description": "The type of this record. Always `funding_package`.", "type": "string", "enum": [ "funding_package" ] }, "id": { "type": "string", "description": "Stable identifier for the funding package." }, "deal_id": { "type": "string", "description": "The deal." }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "voided" ], "description": "`draft`: the broker is still adding documents and checking fields. `sent`, `completed` and `voided` follow the signing of a package that the broker sent from BrokerPlus." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "funding_package_item", "description": "The type of this record. Always `funding_package_item`.", "type": "string", "enum": [ "funding_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "package_id": { "type": "string", "description": "The funding package that holds the item." }, "document_id": { "type": "string", "description": "The document on the deal. Read it with `GET /v1/documents/{id}`." }, "document_name": { "type": "string", "description": "The file name of the document, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package. The first item is 0." }, "recipient_role": { "nullable": true, "description": "The part in the deal of the person who signs the document. Null until it is set.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "nullable": true, "description": "The person who signs the document. Always a participant on the deal. Null until it is set.", "type": "string" }, "recipient_name": { "nullable": true, "description": "The name of the person who signs the document, for display.", "type": "string" }, "has_form_fields": { "type": "boolean", "description": "True when the PDF has form fields that BrokerPlus read. False for a flat PDF: place its fields with `fields`." }, "page_count": { "nullable": true, "description": "The number of pages. Null when the file is not a readable PDF.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the form field in the PDF. It identifies the field in the document." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "nullable": true, "description": "A readable name for the field. Null until the fields are mapped.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "nullable": true, "description": "The deal value that fills the field, as a `key` from `GET /v1/deals/{id}/funding-package/context`. Null when the signer fills it or no value matched.", "type": "string" }, "value": { "nullable": true, "description": "The text that BrokerPlus writes into the field. Only set when `party` is `broker`.", "type": "string" }, "confidence": { "nullable": true, "description": "How sure the mapping is, from 0 to 1. A low value means the broker should check the field.", "type": "number" }, "reviewed": { "type": "boolean", "description": "True when a person confirmed the field." }, "prefilled": { "nullable": true, "description": "The text that the uploaded PDF already had in the field. Null if none.", "type": "string" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "label", "party", "source_key", "value", "confidence", "reviewed", "prefilled" ], "additionalProperties": false }, "description": "The form fields of the document, with who fills each and its value." }, "state": { "type": "string", "enum": [ "pending", "mapped", "reviewed" ], "description": "`pending`: the fields are read but not mapped. `mapped`: BrokerPlus proposed a value for each field. `reviewed`: a person confirmed the fields. Only a `reviewed` item can be sent." }, "created_at": { "type": "string", "description": "When the document was added to the package." }, "updated_at": { "type": "string", "description": "Last change to the item." } }, "required": [ "object", "id", "package_id", "document_id", "document_name", "position", "recipient_role", "recipient_contact_id", "recipient_name", "has_form_fields", "page_count", "fields", "state", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the package was started." }, "updated_at": { "type": "string", "description": "Last change to the package." } }, "required": [ "object", "id", "deal_id", "status", "items", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A document is not on this deal (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/upload": { "post": { "operationId": "uploadDealFundingPackageFiles", "summary": "Upload lender forms to the funding package", "description": "Stores the lender's forms on the deal and adds them to its open funding package, in one request. Send the files as `multipart/form-data` in `files` fields, or as JSON with `content_base64`. The documents are filed as lender funding forms and are not classified.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "string", "format": "binary", "description": "A file. Repeat the field for each file, at most 20. 50 MB maximum each. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." } }, "required": [ "files" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "files": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `pad-form.pdf`." }, "content_type": { "type": "string", "minLength": 1, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false }, "description": "The lender's forms, at most 20." } }, "required": [ "files" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "funding_package", "description": "The type of this record. Always `funding_package`.", "type": "string", "enum": [ "funding_package" ] }, "id": { "type": "string", "description": "Stable identifier for the funding package." }, "deal_id": { "type": "string", "description": "The deal." }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "voided" ], "description": "`draft`: the broker is still adding documents and checking fields. `sent`, `completed` and `voided` follow the signing of a package that the broker sent from BrokerPlus." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "funding_package_item", "description": "The type of this record. Always `funding_package_item`.", "type": "string", "enum": [ "funding_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "package_id": { "type": "string", "description": "The funding package that holds the item." }, "document_id": { "type": "string", "description": "The document on the deal. Read it with `GET /v1/documents/{id}`." }, "document_name": { "type": "string", "description": "The file name of the document, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package. The first item is 0." }, "recipient_role": { "nullable": true, "description": "The part in the deal of the person who signs the document. Null until it is set.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "nullable": true, "description": "The person who signs the document. Always a participant on the deal. Null until it is set.", "type": "string" }, "recipient_name": { "nullable": true, "description": "The name of the person who signs the document, for display.", "type": "string" }, "has_form_fields": { "type": "boolean", "description": "True when the PDF has form fields that BrokerPlus read. False for a flat PDF: place its fields with `fields`." }, "page_count": { "nullable": true, "description": "The number of pages. Null when the file is not a readable PDF.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the form field in the PDF. It identifies the field in the document." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "nullable": true, "description": "A readable name for the field. Null until the fields are mapped.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "nullable": true, "description": "The deal value that fills the field, as a `key` from `GET /v1/deals/{id}/funding-package/context`. Null when the signer fills it or no value matched.", "type": "string" }, "value": { "nullable": true, "description": "The text that BrokerPlus writes into the field. Only set when `party` is `broker`.", "type": "string" }, "confidence": { "nullable": true, "description": "How sure the mapping is, from 0 to 1. A low value means the broker should check the field.", "type": "number" }, "reviewed": { "type": "boolean", "description": "True when a person confirmed the field." }, "prefilled": { "nullable": true, "description": "The text that the uploaded PDF already had in the field. Null if none.", "type": "string" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "label", "party", "source_key", "value", "confidence", "reviewed", "prefilled" ], "additionalProperties": false }, "description": "The form fields of the document, with who fills each and its value." }, "state": { "type": "string", "enum": [ "pending", "mapped", "reviewed" ], "description": "`pending`: the fields are read but not mapped. `mapped`: BrokerPlus proposed a value for each field. `reviewed`: a person confirmed the fields. Only a `reviewed` item can be sent." }, "created_at": { "type": "string", "description": "When the document was added to the package." }, "updated_at": { "type": "string", "description": "Last change to the item." } }, "required": [ "object", "id", "package_id", "document_id", "document_name", "position", "recipient_role", "recipient_contact_id", "recipient_name", "has_form_fields", "page_count", "fields", "state", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the package was started." }, "updated_at": { "type": "string", "description": "Last change to the package." } }, "required": [ "object", "id", "deal_id", "status", "items", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A file is missing, or its type is not allowed (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "A file is larger than the limit for its encoding (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/items/{item_id}/map": { "post": { "operationId": "mapDealFundingPackageItem", "summary": "Map a funding document's fields", "description": "Names each form field of the document, decides who fills it, and proposes its value from the deal, as the Map button does in BrokerPlus. Values come from `GET /v1/deals/{id}/funding-package/context` and are never made up. The item becomes `mapped`, and this replaces the fields it had, including any edits. Check the fields and send `state: reviewed` before the broker sends the package.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "item": { "type": "object", "properties": { "object": { "default": "funding_package_item", "description": "The type of this record. Always `funding_package_item`.", "type": "string", "enum": [ "funding_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "package_id": { "type": "string", "description": "The funding package that holds the item." }, "document_id": { "type": "string", "description": "The document on the deal. Read it with `GET /v1/documents/{id}`." }, "document_name": { "type": "string", "description": "The file name of the document, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package. The first item is 0." }, "recipient_role": { "nullable": true, "description": "The part in the deal of the person who signs the document. Null until it is set.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "nullable": true, "description": "The person who signs the document. Always a participant on the deal. Null until it is set.", "type": "string" }, "recipient_name": { "nullable": true, "description": "The name of the person who signs the document, for display.", "type": "string" }, "has_form_fields": { "type": "boolean", "description": "True when the PDF has form fields that BrokerPlus read. False for a flat PDF: place its fields with `fields`." }, "page_count": { "nullable": true, "description": "The number of pages. Null when the file is not a readable PDF.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the form field in the PDF. It identifies the field in the document." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "nullable": true, "description": "A readable name for the field. Null until the fields are mapped.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "nullable": true, "description": "The deal value that fills the field, as a `key` from `GET /v1/deals/{id}/funding-package/context`. Null when the signer fills it or no value matched.", "type": "string" }, "value": { "nullable": true, "description": "The text that BrokerPlus writes into the field. Only set when `party` is `broker`.", "type": "string" }, "confidence": { "nullable": true, "description": "How sure the mapping is, from 0 to 1. A low value means the broker should check the field.", "type": "number" }, "reviewed": { "type": "boolean", "description": "True when a person confirmed the field." }, "prefilled": { "nullable": true, "description": "The text that the uploaded PDF already had in the field. Null if none.", "type": "string" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "label", "party", "source_key", "value", "confidence", "reviewed", "prefilled" ], "additionalProperties": false }, "description": "The form fields of the document, with who fills each and its value." }, "state": { "type": "string", "enum": [ "pending", "mapped", "reviewed" ], "description": "`pending`: the fields are read but not mapped. `mapped`: BrokerPlus proposed a value for each field. `reviewed`: a person confirmed the fields. Only a `reviewed` item can be sent." }, "created_at": { "type": "string", "description": "When the document was added to the package." }, "updated_at": { "type": "string", "description": "Last change to the item." } }, "required": [ "object", "id", "package_id", "document_id", "document_name", "position", "recipient_role", "recipient_contact_id", "recipient_name", "has_form_fields", "page_count", "fields", "state", "created_at", "updated_at" ], "additionalProperties": false, "description": "The item with the values that the mapping proposed. Its `state` is `mapped`." }, "unmapped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many fields got no value. The broker or the signer fills them." } }, "required": [ "item", "unmapped" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The document has no form fields to map (NO_FIELDS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "BrokerPlus could not read the fields this time. Try again later (MAPPING_FAILED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/items/{item_id}": { "patch": { "operationId": "updateDealFundingPackageItem", "summary": "Update a funding package item", "description": "Sets who signs the document, its order, its fields, or its state. `fields` replaces the whole list.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_role": { "description": "The part in the deal of the person who signs the document. Send null to clear.", "nullable": true, "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "description": "The person who signs the document. Must be a participant on the deal. Send null to clear.", "nullable": true, "type": "string" }, "state": { "description": "Send `reviewed` when a person confirmed the fields. Only a `reviewed` item can be sent.", "type": "string", "enum": [ "pending", "mapped", "reviewed" ] }, "position": { "description": "The order of the item in the package. The first item is 0.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fields": { "description": "Every field of the document. The list replaces the fields that the item has now.", "maxItems": 400, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the form field in the PDF." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "description": "A readable name for the field.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "description": "A `key` from `GET /v1/deals/{id}/funding-package/context`, or null.", "nullable": true, "type": "string" }, "value": { "description": "The text that BrokerPlus writes into the field.", "nullable": true, "type": "string" }, "confidence": { "description": "How sure the mapping is, from 0 to 1.", "nullable": true, "type": "number" }, "reviewed": { "description": "True when a person confirmed the field.", "type": "boolean" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "party" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "funding_package_item", "description": "The type of this record. Always `funding_package_item`.", "type": "string", "enum": [ "funding_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "package_id": { "type": "string", "description": "The funding package that holds the item." }, "document_id": { "type": "string", "description": "The document on the deal. Read it with `GET /v1/documents/{id}`." }, "document_name": { "type": "string", "description": "The file name of the document, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package. The first item is 0." }, "recipient_role": { "nullable": true, "description": "The part in the deal of the person who signs the document. Null until it is set.", "type": "string", "enum": [ "primary_applicant", "co_applicant", "guarantor", "cosigner", "power_of_attorney", "realtor", "lawyer", "appraiser", "lender_contact", "underwriter_contact", "credit_assistant", "insurance", "financial_planner", "accountant", "builder", "other" ] }, "recipient_contact_id": { "nullable": true, "description": "The person who signs the document. Always a participant on the deal. Null until it is set.", "type": "string" }, "recipient_name": { "nullable": true, "description": "The name of the person who signs the document, for display.", "type": "string" }, "has_form_fields": { "type": "boolean", "description": "True when the PDF has form fields that BrokerPlus read. False for a flat PDF: place its fields with `fields`." }, "page_count": { "nullable": true, "description": "The number of pages. Null when the file is not a readable PDF.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the form field in the PDF. It identifies the field in the document." }, "kind": { "type": "string", "enum": [ "signature", "initials", "date", "text", "checkbox" ], "description": "What goes in the field: `signature`, `initials`, `date`, `text` or `checkbox`." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The page the field is on. The first page is 1." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "The left edge, as a fraction of the page width from the left." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "The top edge, as a fraction of the page height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The width, as a fraction of the page width." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1, "description": "The height, as a fraction of the page height." }, "label": { "nullable": true, "description": "A readable name for the field. Null until the fields are mapped.", "type": "string" }, "party": { "type": "string", "enum": [ "broker", "signer", "unknown" ], "description": "Who fills the field. `broker`: BrokerPlus writes `value` into the PDF before it is sent. `signer`: the person who receives the document fills it. `unknown`: nobody decided yet, and the broker must choose before the package can be sent." }, "source_key": { "nullable": true, "description": "The deal value that fills the field, as a `key` from `GET /v1/deals/{id}/funding-package/context`. Null when the signer fills it or no value matched.", "type": "string" }, "value": { "nullable": true, "description": "The text that BrokerPlus writes into the field. Only set when `party` is `broker`.", "type": "string" }, "confidence": { "nullable": true, "description": "How sure the mapping is, from 0 to 1. A low value means the broker should check the field.", "type": "number" }, "reviewed": { "type": "boolean", "description": "True when a person confirmed the field." }, "prefilled": { "nullable": true, "description": "The text that the uploaded PDF already had in the field. Null if none.", "type": "string" } }, "required": [ "name", "kind", "page", "x", "y", "width", "height", "label", "party", "source_key", "value", "confidence", "reviewed", "prefilled" ], "additionalProperties": false }, "description": "The form fields of the document, with who fills each and its value." }, "state": { "type": "string", "enum": [ "pending", "mapped", "reviewed" ], "description": "`pending`: the fields are read but not mapped. `mapped`: BrokerPlus proposed a value for each field. `reviewed`: a person confirmed the fields. Only a `reviewed` item can be sent." }, "created_at": { "type": "string", "description": "When the document was added to the package." }, "updated_at": { "type": "string", "description": "Last change to the item." } }, "required": [ "object", "id", "package_id", "document_id", "document_name", "position", "recipient_role", "recipient_contact_id", "recipient_name", "has_form_fields", "page_count", "fields", "state", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The recipient is not a participant on this deal (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "removeDealFundingPackageItem", "summary": "Remove a document from the funding package", "description": "Takes the document out of the package. The document stays on the deal.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/funding-package/send": { "post": { "operationId": "sendDealFundingPackage", "summary": "Send the funding package for signature", "description": "Sends the funding package for signature now, the same as Send on the deal's Funding tab. BrokerPlus fills each form and puts them in one signing envelope. The signing service emails each person once for the forms that are theirs. Every document must be `reviewed` with a signer who has an email. The response is `201` with the new signing envelope. A key with the `no_sending` limit cannot do this.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_envelope", "description": "The type of this record. Always `signing_envelope`.", "type": "string", "enum": [ "signing_envelope" ] }, "id": { "type": "string", "description": "Stable identifier for the signing envelope." }, "deal_id": { "type": "string", "description": "The deal." }, "funding_package_id": { "nullable": true, "description": "The funding package that went out in this envelope, or null when it was sent for something else.", "type": "string" }, "status": { "type": "string", "description": "Where the signing stands, as the signing service last reported it: `sent` when it went out, then `signed` once everyone has signed, or `declined` or `voided`." }, "document_names": { "type": "array", "items": { "type": "string" }, "description": "The file name of each document in the envelope, in order." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_envelope_recipient", "description": "The type of this record. Always `signing_envelope_recipient`.", "type": "string", "enum": [ "signing_envelope_recipient" ] }, "id": { "type": "string", "description": "Stable identifier for the recipient." }, "contact_id": { "type": "string", "description": "The contact asked to sign." }, "name": { "type": "string", "description": "The contact's name." }, "role": { "type": "string", "enum": [ "signer", "cc", "witness" ], "description": "`signer` signs, `cc` gets a copy, `witness` witnesses." } }, "required": [ "object", "id", "contact_id", "name", "role" ], "additionalProperties": false }, "description": "Each person the envelope went to, once each however many documents name them." }, "created_at": { "type": "string", "description": "When the envelope was sent." }, "updated_at": { "type": "string", "description": "Last change to the envelope." } }, "required": [ "object", "id", "deal_id", "funding_package_id", "status", "document_names", "recipients", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or it has no open funding package (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The signing service refused the package, and nothing was sent (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The package has no documents, or a document is not ready: not reviewed, a field without a value, or a signer without an email. `details.fields` names each one (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-envelopes": { "get": { "operationId": "listDealSigningEnvelopes", "summary": "List a deal's signing envelopes", "description": "Each envelope that went out for signature on this deal, with its documents, the people it went to, and where the signing stands. Newest first.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_envelope", "description": "The type of this record. Always `signing_envelope`.", "type": "string", "enum": [ "signing_envelope" ] }, "id": { "type": "string", "description": "Stable identifier for the signing envelope." }, "deal_id": { "type": "string", "description": "The deal." }, "funding_package_id": { "nullable": true, "description": "The funding package that went out in this envelope, or null when it was sent for something else.", "type": "string" }, "status": { "type": "string", "description": "Where the signing stands, as the signing service last reported it: `sent` when it went out, then `signed` once everyone has signed, or `declined` or `voided`." }, "document_names": { "type": "array", "items": { "type": "string" }, "description": "The file name of each document in the envelope, in order." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_envelope_recipient", "description": "The type of this record. Always `signing_envelope_recipient`.", "type": "string", "enum": [ "signing_envelope_recipient" ] }, "id": { "type": "string", "description": "Stable identifier for the recipient." }, "contact_id": { "type": "string", "description": "The contact asked to sign." }, "name": { "type": "string", "description": "The contact's name." }, "role": { "type": "string", "enum": [ "signer", "cc", "witness" ], "description": "`signer` signs, `cc` gets a copy, `witness` witnesses." } }, "required": [ "object", "id", "contact_id", "name", "role" ], "additionalProperties": false }, "description": "Each person the envelope went to, once each however many documents name them." }, "created_at": { "type": "string", "description": "When the envelope was sent." }, "updated_at": { "type": "string", "description": "Last change to the envelope." } }, "required": [ "object", "id", "deal_id", "funding_package_id", "status", "document_names", "recipients", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-envelopes/{envelopeId}": { "get": { "operationId": "getDealSigningEnvelope", "summary": "Retrieve a signing envelope", "description": "One envelope that went out for signature on this deal.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "envelopeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_envelope", "description": "The type of this record. Always `signing_envelope`.", "type": "string", "enum": [ "signing_envelope" ] }, "id": { "type": "string", "description": "Stable identifier for the signing envelope." }, "deal_id": { "type": "string", "description": "The deal." }, "funding_package_id": { "nullable": true, "description": "The funding package that went out in this envelope, or null when it was sent for something else.", "type": "string" }, "status": { "type": "string", "description": "Where the signing stands, as the signing service last reported it: `sent` when it went out, then `signed` once everyone has signed, or `declined` or `voided`." }, "document_names": { "type": "array", "items": { "type": "string" }, "description": "The file name of each document in the envelope, in order." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_envelope_recipient", "description": "The type of this record. Always `signing_envelope_recipient`.", "type": "string", "enum": [ "signing_envelope_recipient" ] }, "id": { "type": "string", "description": "Stable identifier for the recipient." }, "contact_id": { "type": "string", "description": "The contact asked to sign." }, "name": { "type": "string", "description": "The contact's name." }, "role": { "type": "string", "enum": [ "signer", "cc", "witness" ], "description": "`signer` signs, `cc` gets a copy, `witness` witnesses." } }, "required": [ "object", "id", "contact_id", "name", "role" ], "additionalProperties": false }, "description": "Each person the envelope went to, once each however many documents name them." }, "created_at": { "type": "string", "description": "When the envelope was sent." }, "updated_at": { "type": "string", "description": "Last change to the envelope." } }, "required": [ "object", "id", "deal_id", "funding_package_id", "status", "document_names", "recipients", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/document-templates": { "get": { "operationId": "listDocumentTemplates", "summary": "List document templates", "description": "The branded letter templates that the broker your key acts as can use: their own, and the ones their teams share. Sorted by name.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "document_template", "description": "The type of this record. Always `document_template`.", "type": "string", "enum": [ "document_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template. Send it as `template_id` to generate a document." }, "name": { "type": "string", "description": "The name of the template, as the broker sees it." }, "category": { "type": "string", "enum": [ "approval", "pre_approval", "gift", "consent", "general" ], "description": "What kind of letter the template makes: `approval`, `pre_approval`, `gift`, `consent`, or `general`." }, "team_id": { "nullable": true, "description": "The team that shares the template. `null` for a broker's own template.", "type": "string" }, "include_in_submission": { "type": "boolean", "description": "`true` when a document made from it goes in the lender submission package." }, "expiry_days": { "nullable": true, "description": "How many days a document made from it stays valid. `null` when it does not expire.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string", "description": "When the template was created." }, "updated_at": { "type": "string", "description": "When the template last changed." } }, "required": [ "object", "id", "name", "category", "team_id", "include_in_submission", "expiry_days", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/generated-documents": { "get": { "operationId": "listDealGeneratedDocuments", "summary": "List a deal's generated documents", "description": "The letters made from templates for this deal, newest first.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "generated_document", "description": "The type of this record. Always `generated_document`.", "type": "string", "enum": [ "generated_document" ] }, "id": { "type": "string", "description": "Stable identifier for the generated document." }, "deal_id": { "type": "string", "description": "The deal the document is for." }, "template_id": { "type": "string", "description": "The template it was made from." }, "template_name": { "type": "string", "description": "The name of that template, for display." }, "category": { "type": "string", "enum": [ "approval", "pre_approval", "gift", "consent", "general" ], "description": "The category of that template." }, "status": { "type": "string", "enum": [ "draft", "final" ], "description": "`final`: the PDF is made and filed on the deal as `document_id`. `draft`: something must be fixed first; `issues` says what. The broker fixes a draft in BrokerPlus." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "The kind of issue, for example `gap` or `expiry_missing`." }, "message": { "type": "string", "description": "What to fix, in a sentence." } }, "required": [ "kind", "message" ], "additionalProperties": false }, "description": "What stops a draft from being final. Empty for a final document." }, "page_count": { "nullable": true, "description": "How many pages the PDF has. `null` for a draft.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "nullable": true, "description": "The PDF filed on the deal. Download it with `GET /v1/documents/{id}`. `null` for a draft.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker who made it. `null` when an automation made it.", "type": "string" }, "finalized_at": { "nullable": true, "description": "When the PDF was made.", "type": "string" }, "created_at": { "type": "string", "description": "When it was made." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "template_id", "template_name", "category", "status", "issues", "page_count", "document_id", "created_by_user_id", "finalized_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealGeneratedDocument", "summary": "Generate a document", "description": "Makes a branded letter from a template, with the deal's details filled in, as Generate on the deal does in BrokerPlus. When nothing needs the broker, BrokerPlus makes the PDF and files it on the deal: `status` is `final` and `document_id` is the file. Otherwise `status` is `draft`, and `issues` says what the broker must fix in BrokerPlus. Nothing is sent to anybody. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "string", "description": "The template to use, from `GET /v1/document-templates`." }, "contact_id": { "description": "The person on the deal that the letter is addressed to. Leave it out for a letter to nobody in particular.", "type": "string" }, "expiry_date": { "description": "The date the letter expires, as `YYYY-MM-DD`. The default comes from the template's `expiry_days`.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "template_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "generated_document", "description": "The type of this record. Always `generated_document`.", "type": "string", "enum": [ "generated_document" ] }, "id": { "type": "string", "description": "Stable identifier for the generated document." }, "deal_id": { "type": "string", "description": "The deal the document is for." }, "template_id": { "type": "string", "description": "The template it was made from." }, "template_name": { "type": "string", "description": "The name of that template, for display." }, "category": { "type": "string", "enum": [ "approval", "pre_approval", "gift", "consent", "general" ], "description": "The category of that template." }, "status": { "type": "string", "enum": [ "draft", "final" ], "description": "`final`: the PDF is made and filed on the deal as `document_id`. `draft`: something must be fixed first; `issues` says what. The broker fixes a draft in BrokerPlus." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "The kind of issue, for example `gap` or `expiry_missing`." }, "message": { "type": "string", "description": "What to fix, in a sentence." } }, "required": [ "kind", "message" ], "additionalProperties": false }, "description": "What stops a draft from being final. Empty for a final document." }, "page_count": { "nullable": true, "description": "How many pages the PDF has. `null` for a draft.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "nullable": true, "description": "The PDF filed on the deal. Download it with `GET /v1/documents/{id}`. `null` for a draft.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker who made it. `null` when an automation made it.", "type": "string" }, "finalized_at": { "nullable": true, "description": "When the PDF was made.", "type": "string" }, "created_at": { "type": "string", "description": "When it was made." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "template_id", "template_name", "category", "status", "issues", "page_count", "document_id", "created_by_user_id", "finalized_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the template is not one your key can use (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The contact is not on the deal (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/generated-documents/{documentId}": { "get": { "operationId": "getDealGeneratedDocument", "summary": "Retrieve a generated document", "description": "One letter made from a template. When `status` is `final`, download the PDF with `GET /v1/documents/{document_id}`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "generated_document", "description": "The type of this record. Always `generated_document`.", "type": "string", "enum": [ "generated_document" ] }, "id": { "type": "string", "description": "Stable identifier for the generated document." }, "deal_id": { "type": "string", "description": "The deal the document is for." }, "template_id": { "type": "string", "description": "The template it was made from." }, "template_name": { "type": "string", "description": "The name of that template, for display." }, "category": { "type": "string", "enum": [ "approval", "pre_approval", "gift", "consent", "general" ], "description": "The category of that template." }, "status": { "type": "string", "enum": [ "draft", "final" ], "description": "`final`: the PDF is made and filed on the deal as `document_id`. `draft`: something must be fixed first; `issues` says what. The broker fixes a draft in BrokerPlus." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "The kind of issue, for example `gap` or `expiry_missing`." }, "message": { "type": "string", "description": "What to fix, in a sentence." } }, "required": [ "kind", "message" ], "additionalProperties": false }, "description": "What stops a draft from being final. Empty for a final document." }, "page_count": { "nullable": true, "description": "How many pages the PDF has. `null` for a draft.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "nullable": true, "description": "The PDF filed on the deal. Download it with `GET /v1/documents/{id}`. `null` for a draft.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker who made it. `null` when an automation made it.", "type": "string" }, "finalized_at": { "nullable": true, "description": "When the PDF was made.", "type": "string" }, "created_at": { "type": "string", "description": "When it was made." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "deal_id", "template_id", "template_name", "category", "status", "issues", "page_count", "document_id", "created_by_user_id", "finalized_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/generated-documents/{documentId}/send": { "post": { "operationId": "sendDealGeneratedDocument", "summary": "Email a generated document", "description": "Emails the letter's PDF as an attachment now, from the broker's connected mailbox. BrokerPlus sends it through a draft in the broker's name, so it is in their drafts folder and in Sent. The response is `201` with that draft, with `status` `sent`. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Who gets the email. The contact must be on the deal and must have an email address." }, "subject": { "description": "The subject. The default is the name of the template.", "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "description": "The email text, in plain text. The default is a short note that says what is attached.", "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The document is a draft (DOCUMENT_NOT_FINAL), or the brokerage has no connected email inbox (NO_EMAIL_INBOX).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The contact is not on the deal, or has no email address (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-documents": { "get": { "operationId": "listDealSigningDocuments", "summary": "List a deal's documents to sign", "description": "The deal's signing package: each document a person on the deal signs, with where its signing is. Oldest first.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_document", "description": "The type of this record. Always `signing_document`.", "type": "string", "enum": [ "signing_document" ] }, "id": { "type": "string", "description": "Stable identifier for the signing document." }, "deal_id": { "type": "string", "description": "The deal that the document is on." }, "contact_id": { "nullable": true, "description": "The person who signs it. `null` when the document is on the deal for nobody yet.", "type": "string" }, "title": { "type": "string", "description": "The name of the document, as the signer sees it." }, "description": { "nullable": true, "description": "The note that the signer sees under the name.", "type": "string" }, "requirement_id": { "nullable": true, "description": "The brokerage's saved document that this one was copied from. `null` for a document added to this deal only.", "type": "string" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "viewed", "borrower_signed", "signed", "declined", "voided", "failed" ], "description": "`not_sent`: nobody has been asked to sign it. `sent`: the signer has it in their portal. `viewed`: the signer opened it. `borrower_signed`: the signer signed, and it waits for another signature. `signed`: everyone signed. `declined`: the signer declined to sign. `voided`: the signing was canceled. `failed`: the signing service could not send it." }, "sent_at": { "nullable": true, "description": "When it was first sent to the signer, in ISO 8601 UTC.", "type": "string" }, "signed_at": { "nullable": true, "description": "When everyone had signed, in ISO 8601 UTC.", "type": "string" }, "created_at": { "type": "string", "description": "When the document was added to the deal, in ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "When the document last changed, in ISO 8601 UTC." } }, "required": [ "object", "id", "deal_id", "contact_id", "title", "description", "requirement_id", "status", "sent_at", "signed_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealSigningDocuments", "summary": "Add documents to sign to a deal", "description": "Adds one of the brokerage's saved documents, or each saved document with a form to sign in a preset, to the deal for the person who signs it. Returns `201` with the documents that are on the deal for that person. A document already on the deal for them is returned, not added again. Adding a document sends nothing.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Who signs the documents. The contact must be on the deal." }, "requirement_id": { "description": "A saved document of the brokerage to add. Send this or `preset_id`, not both.", "type": "string" }, "preset_id": { "description": "A preset to apply. Each of its saved documents with a form to sign is added. Send this or `requirement_id`, not both.", "type": "string" } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_document", "description": "The type of this record. Always `signing_document`.", "type": "string", "enum": [ "signing_document" ] }, "id": { "type": "string", "description": "Stable identifier for the signing document." }, "deal_id": { "type": "string", "description": "The deal that the document is on." }, "contact_id": { "nullable": true, "description": "The person who signs it. `null` when the document is on the deal for nobody yet.", "type": "string" }, "title": { "type": "string", "description": "The name of the document, as the signer sees it." }, "description": { "nullable": true, "description": "The note that the signer sees under the name.", "type": "string" }, "requirement_id": { "nullable": true, "description": "The brokerage's saved document that this one was copied from. `null` for a document added to this deal only.", "type": "string" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "viewed", "borrower_signed", "signed", "declined", "voided", "failed" ], "description": "`not_sent`: nobody has been asked to sign it. `sent`: the signer has it in their portal. `viewed`: the signer opened it. `borrower_signed`: the signer signed, and it waits for another signature. `signed`: everyone signed. `declined`: the signer declined to sign. `voided`: the signing was canceled. `failed`: the signing service could not send it." }, "sent_at": { "nullable": true, "description": "When it was first sent to the signer, in ISO 8601 UTC.", "type": "string" }, "signed_at": { "nullable": true, "description": "When everyone had signed, in ISO 8601 UTC.", "type": "string" }, "created_at": { "type": "string", "description": "When the document was added to the deal, in ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "When the document last changed, in ISO 8601 UTC." } }, "required": [ "object", "id", "deal_id", "contact_id", "title", "description", "requirement_id", "status", "sent_at", "signed_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The saved document is already on the deal for somebody else (REQUIREMENT_ALREADY_ASSIGNED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The contact is not on the deal, the saved document or preset was not found, or it has no form to sign (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-documents/{documentId}": { "get": { "operationId": "getDealSigningDocument", "summary": "Retrieve a document to sign", "description": "One document in the deal's signing package, with where its signing is.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_document", "description": "The type of this record. Always `signing_document`.", "type": "string", "enum": [ "signing_document" ] }, "id": { "type": "string", "description": "Stable identifier for the signing document." }, "deal_id": { "type": "string", "description": "The deal that the document is on." }, "contact_id": { "nullable": true, "description": "The person who signs it. `null` when the document is on the deal for nobody yet.", "type": "string" }, "title": { "type": "string", "description": "The name of the document, as the signer sees it." }, "description": { "nullable": true, "description": "The note that the signer sees under the name.", "type": "string" }, "requirement_id": { "nullable": true, "description": "The brokerage's saved document that this one was copied from. `null` for a document added to this deal only.", "type": "string" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "viewed", "borrower_signed", "signed", "declined", "voided", "failed" ], "description": "`not_sent`: nobody has been asked to sign it. `sent`: the signer has it in their portal. `viewed`: the signer opened it. `borrower_signed`: the signer signed, and it waits for another signature. `signed`: everyone signed. `declined`: the signer declined to sign. `voided`: the signing was canceled. `failed`: the signing service could not send it." }, "sent_at": { "nullable": true, "description": "When it was first sent to the signer, in ISO 8601 UTC.", "type": "string" }, "signed_at": { "nullable": true, "description": "When everyone had signed, in ISO 8601 UTC.", "type": "string" }, "created_at": { "type": "string", "description": "When the document was added to the deal, in ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "When the document last changed, in ISO 8601 UTC." } }, "required": [ "object", "id", "deal_id", "contact_id", "title", "description", "requirement_id", "status", "sent_at", "signed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-presets": { "get": { "operationId": "listDealSigningPresets", "summary": "List the signing presets for a deal", "description": "The saved sets of documents a broker can apply to this deal at once: the deal's team's and the brokerage's, for the deal's province or for every province.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_preset", "description": "The type of this record. Always `signing_preset`.", "type": "string", "enum": [ "signing_preset" ] }, "id": { "type": "string", "description": "Stable identifier for the preset." }, "name": { "type": "string", "description": "The name of the preset." }, "owner": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team`: the deal's team saved it. `brokerage`: it is firm policy." }, "provinces": { "type": "array", "items": { "type": "string" }, "description": "The provinces the preset is for, as two-letter codes. An empty list means every province." }, "requirement_ids": { "type": "array", "items": { "type": "string" }, "description": "The brokerage's saved documents in the preset. `POST /v1/deals/{id}/signing-documents` with `preset_id` adds each of these that has a form to sign." } }, "required": [ "object", "id", "name", "owner", "provinces", "requirement_ids" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-documents/{documentId}/preview": { "post": { "operationId": "previewDealSigningDocument", "summary": "Preview a document to sign", "description": "Fills in the document as it would go out now and returns the PDF. Runs the same checks as a send: a document that cannot be sent returns `422` with the reason. Sends nothing and keeps no copy.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_preview", "description": "The type of this record. Always `signing_preview`.", "type": "string", "enum": [ "signing_preview" ] }, "document_id": { "type": "string", "description": "The signing document that was rendered." }, "content_type": { "type": "string", "enum": [ "application/pdf" ], "description": "The type of the file in `pdf_base64`." }, "pdf_base64": { "type": "string", "description": "The filled document as a PDF, base64-encoded." }, "filled_fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "nullable": true, "description": "The name of the field on the form, if it has one.", "type": "string" }, "value": { "type": "string", "description": "What BrokerPlus writes in the field before the signer gets it." } }, "required": [ "label", "value" ], "additionalProperties": false }, "description": "Each field that BrokerPlus fills in for the broker. The signer fills in the rest." } }, "required": [ "object", "document_id", "content_type", "pdf_base64", "filled_fields" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The document is for nobody yet (NO_SIGNER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The document cannot be sent as it is, for example a field the broker fills in is empty. `code` and `message` say what.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-documents/send": { "post": { "operationId": "sendDealSigningDocuments", "summary": "Send documents to sign", "description": "Sends the documents to sign now, the same as Send on the deal's signing package. Each document is filled in and checked, and each person gets one email with a link to the documents that are for them. The response has the documents that this call sent. A key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`: a retry with the same key gets the first response and emails nobody again.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string" }, "description": "The signing documents to send. Each person gets one email with a link to every document that is for them." }, "note": { "description": "The broker's own words in the email. One note for the whole send.", "type": "string", "maxLength": 2000 } }, "required": [ "document_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_document", "description": "The type of this record. Always `signing_document`.", "type": "string", "enum": [ "signing_document" ] }, "id": { "type": "string", "description": "Stable identifier for the signing document." }, "deal_id": { "type": "string", "description": "The deal that the document is on." }, "contact_id": { "nullable": true, "description": "The person who signs it. `null` when the document is on the deal for nobody yet.", "type": "string" }, "title": { "type": "string", "description": "The name of the document, as the signer sees it." }, "description": { "nullable": true, "description": "The note that the signer sees under the name.", "type": "string" }, "requirement_id": { "nullable": true, "description": "The brokerage's saved document that this one was copied from. `null` for a document added to this deal only.", "type": "string" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "viewed", "borrower_signed", "signed", "declined", "voided", "failed" ], "description": "`not_sent`: nobody has been asked to sign it. `sent`: the signer has it in their portal. `viewed`: the signer opened it. `borrower_signed`: the signer signed, and it waits for another signature. `signed`: everyone signed. `declined`: the signer declined to sign. `voided`: the signing was canceled. `failed`: the signing service could not send it." }, "sent_at": { "nullable": true, "description": "When it was first sent to the signer, in ISO 8601 UTC.", "type": "string" }, "signed_at": { "nullable": true, "description": "When everyone had signed, in ISO 8601 UTC.", "type": "string" }, "created_at": { "type": "string", "description": "When the document was added to the deal, in ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "When the document last changed, in ISO 8601 UTC." } }, "required": [ "object", "id", "deal_id", "contact_id", "title", "description", "requirement_id", "status", "sent_at", "signed_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The send was refused, and nothing was sent (NOT_SENT). `message` says why.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "A document is not on the deal, is for nobody, its signer has no email address, or it cannot be sent as it is. `details.fields` names each one (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/signing-documents/{documentId}/resend": { "post": { "operationId": "resendDealSigningDocument", "summary": "Resend a signing link", "description": "Emails the signer a new link to the documents they were sent, now, from the broker who sent them first. The response is the signing document. A key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`: a retry with the same key gets the first response and emails nobody again.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_document", "description": "The type of this record. Always `signing_document`.", "type": "string", "enum": [ "signing_document" ] }, "id": { "type": "string", "description": "Stable identifier for the signing document." }, "deal_id": { "type": "string", "description": "The deal that the document is on." }, "contact_id": { "nullable": true, "description": "The person who signs it. `null` when the document is on the deal for nobody yet.", "type": "string" }, "title": { "type": "string", "description": "The name of the document, as the signer sees it." }, "description": { "nullable": true, "description": "The note that the signer sees under the name.", "type": "string" }, "requirement_id": { "nullable": true, "description": "The brokerage's saved document that this one was copied from. `null` for a document added to this deal only.", "type": "string" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "viewed", "borrower_signed", "signed", "declined", "voided", "failed" ], "description": "`not_sent`: nobody has been asked to sign it. `sent`: the signer has it in their portal. `viewed`: the signer opened it. `borrower_signed`: the signer signed, and it waits for another signature. `signed`: everyone signed. `declined`: the signer declined to sign. `voided`: the signing was canceled. `failed`: the signing service could not send it." }, "sent_at": { "nullable": true, "description": "When it was first sent to the signer, in ISO 8601 UTC.", "type": "string" }, "signed_at": { "nullable": true, "description": "When everyone had signed, in ISO 8601 UTC.", "type": "string" }, "created_at": { "type": "string", "description": "When the document was added to the deal, in ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "When the document last changed, in ISO 8601 UTC." } }, "required": [ "object", "id", "deal_id", "contact_id", "title", "description", "requirement_id", "status", "sent_at", "signed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The document has not been sent yet, or the resend was refused (for example, the sender's email is not connected), and nothing was sent (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/email-attachments": { "get": { "operationId": "listDealEmailAttachments", "summary": "List a deal's email attachments", "description": "Files that came in on email matched to the deal and that BrokerPlus holds for the broker. A held file is not on the deal file: the broker puts it there with accept, or dismisses it. Newest email first. By default only the files that wait for the broker.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "all" ] }, "description": "`pending` (the default) for the files that wait for the broker, `accepted`, `dismissed`, or `all`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "email_attachment", "description": "The type of this record. Always `email_attachment`.", "type": "string", "enum": [ "email_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the attachment." }, "deal_id": { "type": "string", "description": "The deal that the email was matched to." }, "communication_id": { "type": "string", "description": "The email that carried the file. Read it with `GET /v1/communications/{id}`." }, "file_name": { "type": "string", "description": "The file name, as it was on the email." }, "file_type": { "type": "string", "description": "The MIME type, for example `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." }, "subject": { "nullable": true, "description": "The subject of the email. Null if the email had none.", "type": "string" }, "from_name": { "nullable": true, "description": "The display name of the sender. Null if the email gave none.", "type": "string" }, "from_email": { "nullable": true, "description": "The address of the sender.", "type": "string" }, "received_at": { "nullable": true, "description": "When the email arrived.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ], "description": "`pending` waits for the broker and is not on the deal file. `accepted` is on the deal file as `document_id`. `dismissed` was not put on the file." }, "document_id": { "nullable": true, "description": "The deal document that the attachment became. Null until it is accepted.", "type": "string" }, "accepted_at": { "nullable": true, "description": "When the attachment was put on the deal file. Null if it was not.", "type": "string" }, "accepted_by_user_id": { "nullable": true, "description": "The user who put it on the deal file.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the attachment was dismissed. Null if it was not.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The user who dismissed it.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus held the attachment for the broker." }, "updated_at": { "type": "string", "description": "When the attachment last changed." } }, "required": [ "object", "id", "deal_id", "communication_id", "file_name", "file_type", "file_size", "subject", "from_name", "from_email", "received_at", "status", "document_id", "accepted_at", "accepted_by_user_id", "dismissed_at", "dismissed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/email-attachments/{attachmentId}": { "get": { "operationId": "getDealEmailAttachment", "summary": "Retrieve an email attachment", "description": "One file that came in on email matched to the deal, and what the broker did with it.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "email_attachment", "description": "The type of this record. Always `email_attachment`.", "type": "string", "enum": [ "email_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the attachment." }, "deal_id": { "type": "string", "description": "The deal that the email was matched to." }, "communication_id": { "type": "string", "description": "The email that carried the file. Read it with `GET /v1/communications/{id}`." }, "file_name": { "type": "string", "description": "The file name, as it was on the email." }, "file_type": { "type": "string", "description": "The MIME type, for example `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." }, "subject": { "nullable": true, "description": "The subject of the email. Null if the email had none.", "type": "string" }, "from_name": { "nullable": true, "description": "The display name of the sender. Null if the email gave none.", "type": "string" }, "from_email": { "nullable": true, "description": "The address of the sender.", "type": "string" }, "received_at": { "nullable": true, "description": "When the email arrived.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ], "description": "`pending` waits for the broker and is not on the deal file. `accepted` is on the deal file as `document_id`. `dismissed` was not put on the file." }, "document_id": { "nullable": true, "description": "The deal document that the attachment became. Null until it is accepted.", "type": "string" }, "accepted_at": { "nullable": true, "description": "When the attachment was put on the deal file. Null if it was not.", "type": "string" }, "accepted_by_user_id": { "nullable": true, "description": "The user who put it on the deal file.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the attachment was dismissed. Null if it was not.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The user who dismissed it.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus held the attachment for the broker." }, "updated_at": { "type": "string", "description": "When the attachment last changed." } }, "required": [ "object", "id", "deal_id", "communication_id", "file_name", "file_type", "file_size", "subject", "from_name", "from_email", "received_at", "status", "document_id", "accepted_at", "accepted_by_user_id", "dismissed_at", "dismissed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/email-attachments/{attachmentId}/accept": { "post": { "operationId": "acceptDealEmailAttachment", "summary": "Put an email attachment on the deal file", "description": "Puts the file on the deal file as a new document, which BrokerPlus then classifies. `document_id` is the new document. If the file is already on the deal file, you get it as it is.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "email_attachment", "description": "The type of this record. Always `email_attachment`.", "type": "string", "enum": [ "email_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the attachment." }, "deal_id": { "type": "string", "description": "The deal that the email was matched to." }, "communication_id": { "type": "string", "description": "The email that carried the file. Read it with `GET /v1/communications/{id}`." }, "file_name": { "type": "string", "description": "The file name, as it was on the email." }, "file_type": { "type": "string", "description": "The MIME type, for example `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." }, "subject": { "nullable": true, "description": "The subject of the email. Null if the email had none.", "type": "string" }, "from_name": { "nullable": true, "description": "The display name of the sender. Null if the email gave none.", "type": "string" }, "from_email": { "nullable": true, "description": "The address of the sender.", "type": "string" }, "received_at": { "nullable": true, "description": "When the email arrived.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ], "description": "`pending` waits for the broker and is not on the deal file. `accepted` is on the deal file as `document_id`. `dismissed` was not put on the file." }, "document_id": { "nullable": true, "description": "The deal document that the attachment became. Null until it is accepted.", "type": "string" }, "accepted_at": { "nullable": true, "description": "When the attachment was put on the deal file. Null if it was not.", "type": "string" }, "accepted_by_user_id": { "nullable": true, "description": "The user who put it on the deal file.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the attachment was dismissed. Null if it was not.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The user who dismissed it.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus held the attachment for the broker." }, "updated_at": { "type": "string", "description": "When the attachment last changed." } }, "required": [ "object", "id", "deal_id", "communication_id", "file_name", "file_type", "file_size", "subject", "from_name", "from_email", "received_at", "status", "document_id", "accepted_at", "accepted_by_user_id", "dismissed_at", "dismissed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The file was dismissed (ALREADY_RESOLVED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/email-attachments/{attachmentId}/dismiss": { "post": { "operationId": "dismissDealEmailAttachment", "summary": "Dismiss an email attachment", "description": "Keeps the file off the deal file. The email and its attachment stay in the inbox. If the file is already dismissed, you get it as it is.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "email_attachment", "description": "The type of this record. Always `email_attachment`.", "type": "string", "enum": [ "email_attachment" ] }, "id": { "type": "string", "description": "Stable identifier for the attachment." }, "deal_id": { "type": "string", "description": "The deal that the email was matched to." }, "communication_id": { "type": "string", "description": "The email that carried the file. Read it with `GET /v1/communications/{id}`." }, "file_name": { "type": "string", "description": "The file name, as it was on the email." }, "file_type": { "type": "string", "description": "The MIME type, for example `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." }, "subject": { "nullable": true, "description": "The subject of the email. Null if the email had none.", "type": "string" }, "from_name": { "nullable": true, "description": "The display name of the sender. Null if the email gave none.", "type": "string" }, "from_email": { "nullable": true, "description": "The address of the sender.", "type": "string" }, "received_at": { "nullable": true, "description": "When the email arrived.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ], "description": "`pending` waits for the broker and is not on the deal file. `accepted` is on the deal file as `document_id`. `dismissed` was not put on the file." }, "document_id": { "nullable": true, "description": "The deal document that the attachment became. Null until it is accepted.", "type": "string" }, "accepted_at": { "nullable": true, "description": "When the attachment was put on the deal file. Null if it was not.", "type": "string" }, "accepted_by_user_id": { "nullable": true, "description": "The user who put it on the deal file.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the attachment was dismissed. Null if it was not.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The user who dismissed it.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus held the attachment for the broker." }, "updated_at": { "type": "string", "description": "When the attachment last changed." } }, "required": [ "object", "id", "deal_id", "communication_id", "file_name", "file_type", "file_size", "subject", "from_name", "from_email", "received_at", "status", "document_id", "accepted_at", "accepted_by_user_id", "dismissed_at", "dismissed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The file is already on the deal file (ALREADY_RESOLVED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/document-types": { "get": { "operationId": "listDocumentTypes", "summary": "List document types", "description": "The codes BrokerPlus uses for `document_type`, with a readable name and the folder each type goes in. Send one as `document_type` on an upload.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The value to send as `document_type`, and to read back on a document." }, "label": { "type": "string", "description": "The readable name." }, "folder": { "nullable": true, "description": "The folder a verified document of this type goes in. Null means the `other` folder.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] } }, "required": [ "code", "label", "folder" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/hub-resources": { "get": { "operationId": "listHubResources", "summary": "List the PDFs in the client hub", "description": "The PDFs on the Resources tab of a client's hub, oldest first, for example a guide for first-time buyers. Without `deal_id`, the brokerage PDFs that every client sees. With `deal_id`, the PDFs for that deal's client alone. A list never contains a download URL.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "List the PDFs for this deal's client alone, not the brokerage PDFs." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "hub_resource", "description": "The type of this record. Always `hub_resource`.", "type": "string", "enum": [ "hub_resource" ] }, "id": { "type": "string", "description": "Stable identifier for the resource." }, "deal_id": { "nullable": true, "description": "The deal whose client alone sees this PDF. Null for a brokerage PDF, which every client sees in their hub.", "type": "string" }, "name": { "type": "string", "description": "The name the client sees on the Resources tab of their hub." }, "file_name": { "type": "string", "description": "The name of the file that was uploaded." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file in bytes." }, "created_at": { "type": "string", "description": "When the PDF was added." } }, "required": [ "object", "id", "deal_id", "name", "file_name", "file_size", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "uploadHubResource", "summary": "Add a PDF to the client hub", "description": "Adds a PDF to the Resources tab, as Client Requests > Resources in BrokerPlus does. Send `deal_id` to add it for that deal's client alone; without it, every client sees it. Send the file as `multipart/form-data` (fields `file`, `name`, `deal_id`), or as JSON with `content_base64`. Only a PDF of at most 20 MB is accepted, and each list holds at most 12. BrokerPlus does not tell the client, but the client sees the file at once, so a key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The file name, for example `first-time-buyer-guide.pdf`." }, "content_base64": { "type": "string", "minLength": 1, "description": "The PDF, base64-encoded. Send a file larger than the base64 limit as multipart/form-data." }, "name": { "description": "The name the client sees. Leave it out to use the file name without `.pdf`.", "type": "string", "maxLength": 120 }, "deal_id": { "description": "Add the PDF for this deal's client alone. Leave it out to add it for every client.", "type": "string" } }, "required": [ "file_name", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "hub_resource", "description": "The type of this record. Always `hub_resource`.", "type": "string", "enum": [ "hub_resource" ] }, "id": { "type": "string", "description": "Stable identifier for the resource." }, "deal_id": { "nullable": true, "description": "The deal whose client alone sees this PDF. Null for a brokerage PDF, which every client sees in their hub.", "type": "string" }, "name": { "type": "string", "description": "The name the client sees on the Resources tab of their hub." }, "file_name": { "type": "string", "description": "The name of the file that was uploaded." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file in bytes." }, "created_at": { "type": "string", "description": "When the PDF was added." } }, "required": [ "object", "id", "deal_id", "name", "file_name", "file_size", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is empty (NO_FILE), not a PDF (INVALID_TYPE), or the list is full (LIMIT_REACHED), or a field is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "The file is too large (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/hub-resources/{id}": { "delete": { "operationId": "deleteHubResource", "summary": "Remove a PDF from the client hub", "description": "Removes the PDF from the Resources tab and from storage. You cannot undo this. A PDF for one deal's client needs write access to that deal.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/custom-document-types": { "get": { "operationId": "listCustomDocumentTypes", "summary": "List the team's own document types", "description": "The documents the broker's team asks for that are not in `GET /v1/document-types`, by label. The team adds them in its document library in BrokerPlus. Each has a `custom:` code that a document package can name.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "custom_document_type", "description": "The type of this record. Always `custom_document_type`.", "type": "string", "enum": [ "custom_document_type" ] }, "id": { "type": "string", "description": "Stable identifier for the document type." }, "code": { "type": "string", "description": "The code to ask for this document by, for example `custom:gift_letter_from_parents_4d4c4a2e`. BrokerPlus makes it from the label when you create the type, and it does not change." }, "label": { "type": "string", "description": "The name of the document, as the client sees it. Unique in the team." }, "category": { "nullable": true, "description": "The shelf of the document library the type is on. Null puts it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "description": { "nullable": true, "description": "What the broker wants, in a sentence the client sees. Null if none.", "type": "string" }, "created_at": { "type": "string", "description": "When the type was added." }, "updated_at": { "type": "string", "description": "When the type last changed." } }, "required": [ "object", "id", "code", "label", "category", "description", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCustomDocumentType", "summary": "Add a document type to the team", "description": "Adds a document to the team's library, as Add Document in the BrokerPlus document library does. BrokerPlus makes its `code` from the label. Nothing reaches a client. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The name of the document. Another type in the team must not have it." }, "category": { "description": "The shelf of the document library to put the type on. Leave it out for Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "description": { "description": "What the broker wants, in at most 400 characters. The client sees it under the document.", "type": "string", "maxLength": 400 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "custom_document_type", "description": "The type of this record. Always `custom_document_type`.", "type": "string", "enum": [ "custom_document_type" ] }, "id": { "type": "string", "description": "Stable identifier for the document type." }, "code": { "type": "string", "description": "The code to ask for this document by, for example `custom:gift_letter_from_parents_4d4c4a2e`. BrokerPlus makes it from the label when you create the type, and it does not change." }, "label": { "type": "string", "description": "The name of the document, as the client sees it. Unique in the team." }, "category": { "nullable": true, "description": "The shelf of the document library the type is on. Null puts it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "description": { "nullable": true, "description": "What the broker wants, in a sentence the client sees. Null if none.", "type": "string" }, "created_at": { "type": "string", "description": "When the type was added." }, "updated_at": { "type": "string", "description": "When the type last changed." } }, "required": [ "object", "id", "code", "label", "category", "description", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team already has a document type with this label (DUPLICATE_LABEL), or the broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/custom-document-types/{id}": { "get": { "operationId": "getCustomDocumentType", "summary": "Retrieve one of the team's own document types", "description": "One document type of the broker's team. A type that was removed is not found.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "custom_document_type", "description": "The type of this record. Always `custom_document_type`.", "type": "string", "enum": [ "custom_document_type" ] }, "id": { "type": "string", "description": "Stable identifier for the document type." }, "code": { "type": "string", "description": "The code to ask for this document by, for example `custom:gift_letter_from_parents_4d4c4a2e`. BrokerPlus makes it from the label when you create the type, and it does not change." }, "label": { "type": "string", "description": "The name of the document, as the client sees it. Unique in the team." }, "category": { "nullable": true, "description": "The shelf of the document library the type is on. Null puts it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "description": { "nullable": true, "description": "What the broker wants, in a sentence the client sees. Null if none.", "type": "string" }, "created_at": { "type": "string", "description": "When the type was added." }, "updated_at": { "type": "string", "description": "When the type last changed." } }, "required": [ "object", "id", "code", "label", "category", "description", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCustomDocumentType", "summary": "Remove a document type from the team", "description": "Takes the type out of the team's library, so nobody can ask for it again. A request that a client already has keeps asking for it under its label.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/doc-packages": { "get": { "operationId": "listDocPackages", "summary": "List document packages", "description": "The document packages of the broker's team, by name. A package is a named set of documents that the team asks for together, for example `Self-Employed Ontario`. In BrokerPlus, adding a package to a request ticks its documents. To ask a client for them through the API, send its `document_types` to `POST /v1/deals/{id}/document-requests`.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "doc_package", "description": "The type of this record. Always `doc_package`.", "type": "string", "enum": [ "doc_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "name": { "type": "string", "description": "The package name, for example `Self-Employed Ontario`. Unique in the team." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The documents the package asks for: codes from `GET /v1/document-types`, or `custom:` codes from `GET /v1/custom-document-types`." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." }, "condition_key": { "nullable": true, "description": "The situation that recommends this package on a deal's next request, for example `purpose_renewal`. The keys are on `GET /v1/doc-packages/samples`. Null for a package that the broker adds by hand only.", "type": "string" }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "When the package last changed." } }, "required": [ "object", "id", "name", "document_types", "notes", "condition_key", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDocPackage", "summary": "Create a document package", "description": "Adds a package to the broker's team, as Client Requests > Packages in BrokerPlus does. Nothing reaches a client. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The package name. Another package in the team must not have it." }, "document_types": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "The document codes, 1 to 60. A code that is in the list two times is kept one time." }, "notes": { "description": "A note of at most 160 characters under each document, keyed by code. A note for a code that is not in `document_types` is dropped.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 160 } }, "condition_key": { "description": "The situation that recommends this package. Use a `key` from `GET /v1/doc-packages/samples`.", "nullable": true, "type": "string" } }, "required": [ "name", "document_types" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "doc_package", "description": "The type of this record. Always `doc_package`.", "type": "string", "enum": [ "doc_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "name": { "type": "string", "description": "The package name, for example `Self-Employed Ontario`. Unique in the team." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The documents the package asks for: codes from `GET /v1/document-types`, or `custom:` codes from `GET /v1/custom-document-types`." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." }, "condition_key": { "nullable": true, "description": "The situation that recommends this package on a deal's next request, for example `purpose_renewal`. The keys are on `GET /v1/doc-packages/samples`. Null for a package that the broker adds by hand only.", "type": "string" }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "When the package last changed." } }, "required": [ "object", "id", "name", "document_types", "notes", "condition_key", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A field is not valid. `details.field` names it (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team already has a package with this name (DUPLICATE_NAME), or the broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/doc-packages/samples": { "get": { "operationId": "listDocPackageSamples", "summary": "List sample document packages", "description": "The situations BrokerPlus can recognize on a submitted application, each as the package it starts out as. Add one to the team with `POST /v1/doc-packages/samples/{key}`.", "tags": [ "Documents" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The situation key. Send it to `POST /v1/doc-packages/samples/{key}`." }, "situation": { "type": "string", "description": "The situation in words, for example `They are renewing or transferring`." }, "name": { "type": "string", "description": "The name the package gets when you add it." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The document codes the package starts with." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." } }, "required": [ "key", "situation", "name", "document_types", "notes" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/doc-packages/samples/{key}": { "post": { "operationId": "addDocPackageSample", "summary": "Add a sample document package", "description": "Adds the sample for this situation to the team as an ordinary package. You can then change it like any other package. Nothing reaches a client.", "tags": [ "Documents" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "doc_package", "description": "The type of this record. Always `doc_package`.", "type": "string", "enum": [ "doc_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "name": { "type": "string", "description": "The package name, for example `Self-Employed Ontario`. Unique in the team." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The documents the package asks for: codes from `GET /v1/document-types`, or `custom:` codes from `GET /v1/custom-document-types`." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." }, "condition_key": { "nullable": true, "description": "The situation that recommends this package on a deal's next request, for example `purpose_renewal`. The keys are on `GET /v1/doc-packages/samples`. Null for a package that the broker adds by hand only.", "type": "string" }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "When the package last changed." } }, "required": [ "object", "id", "name", "document_types", "notes", "condition_key", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No sample has this key (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team already has a package with this name (DUPLICATE_NAME), or the broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/doc-packages/{id}": { "get": { "operationId": "getDocPackage", "summary": "Retrieve a document package", "description": "One package of the broker's team, with its documents and the note under each.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "doc_package", "description": "The type of this record. Always `doc_package`.", "type": "string", "enum": [ "doc_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "name": { "type": "string", "description": "The package name, for example `Self-Employed Ontario`. Unique in the team." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The documents the package asks for: codes from `GET /v1/document-types`, or `custom:` codes from `GET /v1/custom-document-types`." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." }, "condition_key": { "nullable": true, "description": "The situation that recommends this package on a deal's next request, for example `purpose_renewal`. The keys are on `GET /v1/doc-packages/samples`. Null for a package that the broker adds by hand only.", "type": "string" }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "When the package last changed." } }, "required": [ "object", "id", "name", "document_types", "notes", "condition_key", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDocPackage", "summary": "Update a document package", "description": "Changes only the fields you send. A request already sent to a client keeps the documents it asked for: a package is copied into a request, never linked.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The package name. Another package in the team must not have it." }, "document_types": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "The document codes, 1 to 60. A code that is in the list two times is kept one time." }, "notes": { "description": "A note of at most 160 characters under each document, keyed by code. A note for a code that is not in `document_types` is dropped.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 160 } }, "condition_key": { "description": "The situation that recommends this package. Use a `key` from `GET /v1/doc-packages/samples`.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "doc_package", "description": "The type of this record. Always `doc_package`.", "type": "string", "enum": [ "doc_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "name": { "type": "string", "description": "The package name, for example `Self-Employed Ontario`. Unique in the team." }, "document_types": { "type": "array", "items": { "type": "string" }, "description": "The documents the package asks for: codes from `GET /v1/document-types`, or `custom:` codes from `GET /v1/custom-document-types`." }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The broker's note under each document, keyed by document code, for example `{\"noa\": \"2024 and 2025, both pages\"}`. The client sees each note as one line under the document." }, "condition_key": { "nullable": true, "description": "The situation that recommends this package on a deal's next request, for example `purpose_renewal`. The keys are on `GET /v1/doc-packages/samples`. Null for a package that the broker adds by hand only.", "type": "string" }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "When the package last changed." } }, "required": [ "object", "id", "name", "document_types", "notes", "condition_key", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A field is not valid. `details.field` names it (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team already has a package with this name (DUPLICATE_NAME).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDocPackage", "summary": "Delete a document package", "description": "Deletes the package. You cannot undo this. A request already sent to a client keeps the documents it asked for.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/conditions": { "get": { "operationId": "listDealConditions", "summary": "List a deal's conditions", "description": "What the lender and broker still need, highest priority first. Filter by `status` for open ones.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "outstanding", "needs_review", "submitted", "satisfied", "waived", "rejected" ] }, "description": "Filter by broker-owned status, e.g. `outstanding`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealCondition", "summary": "Add a condition to a deal", "description": "Adds a condition the same way the deal's Conditions tab does. BrokerPlus also files a task to decide it. The condition records your key's broker as the filer. Use `assignee_role` and `assignee_contact_id` to say who owes it. Supports `Idempotency-Key`.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What has to be satisfied. Required." }, "description": { "description": "Longer detail.", "nullable": true, "type": "string", "maxLength": 20000 }, "category": { "description": "The checklist group. Defaults to `other`.", "type": "string", "enum": [ "income", "employment", "property", "credit", "down_payment", "legal", "insurance", "appraisal", "other" ] }, "priority": { "description": "Defaults to `normal`.", "type": "string", "enum": [ "urgent", "high", "normal", "low" ] }, "due_date": { "description": "The date the condition is due, as `YYYY-MM-DD`.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "assignee_role": { "description": "Who owes the condition. Use `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`, or your own value. Send null to clear it.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 64 }, "assignee_contact_id": { "description": "A contact in your brokerage who owes the condition, e.g. the lawyer. Send null to clear it.", "nullable": true, "type": "string" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The assignee contact is not in your brokerage (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/condition-requests": { "post": { "operationId": "requestDealConditions", "summary": "Email somebody on a deal about conditions", "description": "Emails a letter that explains conditions in plain language now, from the broker's connected mailbox, as Request From Participant on the deal's Conditions tab does. A borrower gets a request for what the lender needs. A professional on the deal, for example a realtor or a lawyer, gets an update. BrokerPlus writes the letter and sends it through a draft in the broker's name. The response is `201` with that draft, with `status` `sent`. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "condition_ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "The conditions to explain, from `GET /v1/deals/{id}/conditions`. Each must be on this deal." }, "contact_id": { "type": "string", "description": "Who gets the letter. The contact must be on the deal (`GET /v1/deals/{id}/participants`) and must have an email address. A borrower gets a request for what the lender needs. A professional on the deal, for example a realtor or a lawyer, gets an update." }, "subject": { "description": "Replaces the subject that BrokerPlus writes.", "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "description": "Replaces the letter that BrokerPlus writes, in plain text. Leave it out to send the letter from the app, which explains each condition in plain language.", "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "condition_ids", "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The brokerage has no connected email inbox (NO_EMAIL_INBOX).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "A condition is not on this deal, the contact is not on the deal, or the contact has no email address (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/flags": { "get": { "operationId": "listDealFlags", "summary": "List a deal's flags", "description": "The flags up on the deal now, oldest first. A flag paints the deal's card red on the board. The broker raises at most one by hand, a Pulse automation can raise its own, and each one carries its reason in plain words.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_flag", "description": "The type of this record. Always `deal_flag`.", "type": "string", "enum": [ "deal_flag" ] }, "id": { "type": "string", "description": "The flag. Use it to clear a flag the broker raised." }, "deal_id": { "type": "string", "description": "The deal the flag is on." }, "severity": { "type": "string", "enum": [ "critical", "warn" ], "description": "`critical` for a file losing time right now, `warn` for one drifting toward it." }, "raised_by": { "type": "string", "enum": [ "broker", "automation", "brokerplus" ], "description": "Who put the flag up. `broker` is the one flag a broker raises by hand, and the only one you can raise or clear here. `automation` is a Pulse automation, which clears its own flag. `brokerplus` is BrokerPlus itself." }, "reason": { "type": "string", "description": "Why the deal is flagged, in plain words, as the card shows it." }, "reason_code": { "type": "string", "enum": [ "written", "unspecified" ], "description": "A stable code for the reason. `written` means `reason` is the words a broker or an automation wrote. `unspecified` means BrokerPlus raised it without words of its own. New codes can be added." }, "raised_at": { "type": "string", "description": "ISO 8601. When the flag went up." }, "cleared_at": { "nullable": true, "description": "ISO 8601. When the flag was cleared. Null while it is up, which is every flag the list returns.", "type": "string" } }, "required": [ "object", "id", "deal_id", "severity", "raised_by", "reason", "reason_code", "raised_at", "cleared_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "raiseDealFlag", "summary": "Flag a deal", "description": "Raises the broker's own flag on the deal, as the flag button on the card does. A deal holds one such flag: sending again changes its words and severity, and keeps the time it went up. Nobody outside BrokerPlus sees a flag.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 280, "description": "What the broker sees on the card, 1 to 280 characters." }, "severity": { "default": "critical", "description": "`critical` (the default) or `warn`.", "type": "string", "enum": [ "critical", "warn" ] } }, "required": [ "message", "severity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_flag", "description": "The type of this record. Always `deal_flag`.", "type": "string", "enum": [ "deal_flag" ] }, "id": { "type": "string", "description": "The flag. Use it to clear a flag the broker raised." }, "deal_id": { "type": "string", "description": "The deal the flag is on." }, "severity": { "type": "string", "enum": [ "critical", "warn" ], "description": "`critical` for a file losing time right now, `warn` for one drifting toward it." }, "raised_by": { "type": "string", "enum": [ "broker", "automation", "brokerplus" ], "description": "Who put the flag up. `broker` is the one flag a broker raises by hand, and the only one you can raise or clear here. `automation` is a Pulse automation, which clears its own flag. `brokerplus` is BrokerPlus itself." }, "reason": { "type": "string", "description": "Why the deal is flagged, in plain words, as the card shows it." }, "reason_code": { "type": "string", "enum": [ "written", "unspecified" ], "description": "A stable code for the reason. `written` means `reason` is the words a broker or an automation wrote. `unspecified` means BrokerPlus raised it without words of its own. New codes can be added." }, "raised_at": { "type": "string", "description": "ISO 8601. When the flag went up." }, "cleared_at": { "nullable": true, "description": "ISO 8601. When the flag was cleared. Null while it is up, which is every flag the list returns.", "type": "string" } }, "required": [ "object", "id", "deal_id", "severity", "raised_by", "reason", "reason_code", "raised_at", "cleared_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/flags/{flagId}/clear": { "post": { "operationId": "clearDealFlag", "summary": "Clear the broker's flag", "description": "Takes down the flag the broker raised. A flag from an automation or from BrokerPlus is read-only here: the automation clears its own when the problem is over, and a broker can clear it in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "flagId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_flag", "description": "The type of this record. Always `deal_flag`.", "type": "string", "enum": [ "deal_flag" ] }, "id": { "type": "string", "description": "The flag. Use it to clear a flag the broker raised." }, "deal_id": { "type": "string", "description": "The deal the flag is on." }, "severity": { "type": "string", "enum": [ "critical", "warn" ], "description": "`critical` for a file losing time right now, `warn` for one drifting toward it." }, "raised_by": { "type": "string", "enum": [ "broker", "automation", "brokerplus" ], "description": "Who put the flag up. `broker` is the one flag a broker raises by hand, and the only one you can raise or clear here. `automation` is a Pulse automation, which clears its own flag. `brokerplus` is BrokerPlus itself." }, "reason": { "type": "string", "description": "Why the deal is flagged, in plain words, as the card shows it." }, "reason_code": { "type": "string", "enum": [ "written", "unspecified" ], "description": "A stable code for the reason. `written` means `reason` is the words a broker or an automation wrote. `unspecified` means BrokerPlus raised it without words of its own. New codes can be added." }, "raised_at": { "type": "string", "description": "ISO 8601. When the flag went up." }, "cleared_at": { "nullable": true, "description": "ISO 8601. When the flag was cleared. Null while it is up, which is every flag the list returns.", "type": "string" } }, "required": [ "object", "id", "deal_id", "severity", "raised_by", "reason", "reason_code", "raised_at", "cleared_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No flag with this id is up on the deal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The flag was not raised by a broker (SYSTEM_FLAG).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/checkpoints": { "get": { "operationId": "listDealCheckpoints", "summary": "List a deal's checklist", "description": "The steps on the checklist of the deal's team, in order, each with its value on this deal. A step nobody has set has `value` null. A deal with no team has no checklist, so the list is empty.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_checkpoint", "description": "The type of this record. Always `deal_checkpoint`.", "type": "string", "enum": [ "deal_checkpoint" ] }, "id": { "type": "string", "description": "The checklist step. Use it as `checkpointId` to set the step on this deal." }, "key": { "type": "string", "description": "A stable name for the step, e.g. `appraisal_ordered`. It stays when the label changes." }, "label": { "type": "string", "description": "The step as the team's checklist shows it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step sits in the checklist, from the top." }, "value": { "nullable": true, "description": "`true` when the step is done, `false` when somebody marked it not done, null when nobody has set it.", "type": "boolean" }, "completed_at": { "nullable": true, "description": "ISO 8601. When the step was marked done. Null unless `value` is true.", "type": "string" } }, "required": [ "object", "id", "key", "label", "position", "value", "completed_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/checkpoints/{checkpointId}": { "patch": { "operationId": "setDealCheckpoint", "summary": "Set a checklist step on a deal", "description": "Marks one step done, not done, or unset on this deal, as a click on the deal's checklist does. The step must be on the checklist of the deal's team.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "checkpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "description": "`true` marks the step done, `false` marks it not done, and null clears it back to unset.", "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_checkpoint", "description": "The type of this record. Always `deal_checkpoint`.", "type": "string", "enum": [ "deal_checkpoint" ] }, "id": { "type": "string", "description": "The checklist step. Use it as `checkpointId` to set the step on this deal." }, "key": { "type": "string", "description": "A stable name for the step, e.g. `appraisal_ordered`. It stays when the label changes." }, "label": { "type": "string", "description": "The step as the team's checklist shows it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step sits in the checklist, from the top." }, "value": { "nullable": true, "description": "`true` when the step is done, `false` when somebody marked it not done, null when nobody has set it.", "type": "boolean" }, "completed_at": { "nullable": true, "description": "ISO 8601. When the step was marked done. Null unless `value` is true.", "type": "string" } }, "required": [ "object", "id", "key", "label", "position", "value", "completed_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tags": { "get": { "operationId": "listDealTagsOnDeal", "summary": "List a deal's tags", "description": "Only the tags currently on this deal. For the full vocabulary see `GET /deal-tags`.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "assignDealTag", "summary": "Put a tag on a deal", "description": "Assigning a tag the deal already has is a no-op, not an error.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "string", "description": "A tag id from `GET /contact-tags` or `GET /deal-tags`." } }, "required": [ "tag_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tag", "description": "The type of this record. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass this to the assign and remove endpoints." }, "name": { "type": "string", "description": "The label brokers see. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "is_type": { "type": "boolean", "description": "True when the tag is one of the brokerage's contact types, shown in the Type row of a contact. It assigns and filters like any other tag. Always false on a deal tag." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order." } }, "required": [ "object", "id", "name", "color", "position", "is_type", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tags/{tagId}": { "delete": { "operationId": "removeDealTag", "summary": "Take a tag off a deal", "description": "Idempotent - removing a tag that was not there still returns 200.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/custom-fields": { "get": { "operationId": "listDealCustomFields", "summary": "List a deal's custom fields", "description": "Every custom field the brokerage keeps on a deal, with this deal's value. A field that nobody has answered returns a `value` of `null`, so the list is the same length on every deal.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/custom-fields/{key}": { "patch": { "operationId": "setDealCustomField", "summary": "Set a custom field on a deal", "description": "Sets one field by its `key`. The write is idempotent: the same request twice leaves the same value. Send an empty string to clear the field, which makes it unanswered again.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to store, as text. A `short_text` field takes one line of 200 characters or fewer, and line breaks change to spaces. A `number`,`money` or `percent` field takes a number like `1200` or `4.5`, a `date` field takes `YYYY-MM-DD`, a `checkbox` takes `true` or `false`, a `url` takes a full web address, a `select` field takes one of its options, and a `multi_select` field takes a JSON array of its options, like `[\"Appraisal\",\"Insurance\"]`. Send an empty string to clear the field." } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The value does not fit the field's type or its options (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live field has that `key` on a deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/sender": { "get": { "operationId": "getDealSender", "summary": "See who a deal's mail goes out as", "description": "The broker, the mailbox and the brand that client email on this deal uses. BrokerPlus resolves it the same way a send does, from the deal's assigned broker. To change it, assign another broker, or change the team's brand in BrokerPlus. You cannot set the sender through the API.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal." }, "sender_user_id": { "nullable": true, "description": "The broker whose name and signature the client sees. A team member who does not send as themselves sends as the team's broker. Null when the deal has no broker.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker assigned to the deal.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "mailbox": { "nullable": true, "description": "The email address the mail leaves from. Null when no connected mailbox can send for this deal, so email to the client cannot go.", "type": "string" }, "team_id": { "nullable": true, "description": "The broker team that owns the deal. Its brand paints client mail.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of that team.", "type": "string" }, "brand": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` when the team set its own brand. `brokerage` when it uses the brokerage brand." }, "primary_color": { "type": "string", "description": "Hex color of headings and buttons in client mail." }, "secondary_color": { "type": "string", "description": "Hex accent color." }, "logo_url": { "nullable": true, "description": "The logo at the top of client mail. Null shows no logo.", "type": "string" } }, "required": [ "source", "primary_color", "secondary_color", "logo_url" ], "additionalProperties": false, "description": "The brand that client mail and documents for this deal use." }, "legal_name": { "nullable": true, "description": "The business name in the footer of marketing mail, from the brokerage's sender identity. It is the same for every team.", "type": "string" } }, "required": [ "deal_id", "sender_user_id", "sender_name", "assigned_broker_id", "assigned_broker_name", "mailbox", "team_id", "team_name", "brand", "legal_name" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Retrieve a document", "description": "The document's metadata plus a signed download URL valid for five minutes. Follow it, do not store it.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document", "description": "The type of this record. Always `document`.", "type": "string", "enum": [ "document" ] }, "id": { "type": "string", "description": "Stable identifier for the document." }, "deal_id": { "type": "string", "description": "The deal this document is filed under." }, "contact_id": { "nullable": true, "description": "The borrower it belongs to, when the file names one.", "type": "string" }, "contact_name": { "nullable": true, "description": "The full name of that borrower, for display. Null when `contact_id` is null.", "type": "string" }, "file_name": { "type": "string", "description": "Original filename as uploaded." }, "display_name": { "nullable": true, "description": "The name brokers see in BrokerPlus. A broker can type it, or BrokerPlus makes it from the document type. Null until either occurs.", "type": "string" }, "file_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs. `GET /v1/document-types` lists the codes." }, "document_type_label": { "nullable": true, "description": "The readable name of `document_type`, e.g. `Paystub`. Null for `unknown` and for a custom type.", "type": "string" }, "classification_status": { "type": "string", "description": "`pending`, `classified`, or `needs_review`. New values can appear as the classifier grows." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "Where the document is on the deal's document board. `pending` and `review` both mean received and not yet checked. `verified` means checked and ready to go to a lender." }, "verified": { "type": "boolean", "description": "`true` when `stage` is `verified`. Filter the list with `verified=true`." }, "folder": { "nullable": true, "description": "The folder of a verified document, e.g. `income` or `down_payment`. `unsorted` means a broker has not filed it yet. Null when the document is not verified.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] }, "uploaded_via": { "type": "string", "enum": [ "portal", "email", "manual", "api", "assembled", "generated" ], "description": "How it arrived: `manual` (a broker), `api` (this API), `email` (an email attachment), `portal` (the client), `generated` or `assembled` (made in BrokerPlus)." }, "uploaded_by_user_id": { "nullable": true, "description": "The broker who added the file. Null when the client, an email, or BrokerPlus added it.", "type": "string" }, "uploaded_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments when a document is replaced rather than added." }, "excluded_from_submission": { "type": "boolean", "description": "True when the broker has marked the file as one that does not go to a lender, e.g. a duplicate or a working copy. A new lender submission leaves it out unless the broker picks it." }, "created_at": { "type": "string", "description": "When the document was uploaded." }, "updated_at": { "type": "string", "description": "Last change to its metadata or classification." }, "download_url": { "type": "string", "description": "Short-lived signed URL. Expires in 5 minutes - fetch it, do not store it." }, "download_url_expires_at": { "type": "string", "description": "When that URL stops working." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "file_name", "display_name", "file_type", "file_size", "document_type", "document_type_label", "classification_status", "stage", "verified", "folder", "uploaded_via", "uploaded_by_user_id", "uploaded_by_name", "version", "excluded_from_submission", "created_at", "updated_at", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDocument", "summary": "Update a document", "description": "Rename the document, file it under another borrower on the deal, or keep it out of a new lender submission. Only the fields you send change.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "description": "The name brokers see in BrokerPlus. Send `null` or an empty string to give the naming back to BrokerPlus, which names the file from its document type.", "nullable": true, "type": "string", "maxLength": 200 }, "contact_id": { "description": "File the document under this borrower. The contact must be an applicant on the deal, not a partner such as a realtor. Send `null` to file it under no borrower.", "nullable": true, "type": "string" }, "excluded_from_submission": { "description": "`true` keeps the file out of a new lender submission, for example a duplicate or a working copy.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document", "description": "The type of this record. Always `document`.", "type": "string", "enum": [ "document" ] }, "id": { "type": "string", "description": "Stable identifier for the document." }, "deal_id": { "type": "string", "description": "The deal this document is filed under." }, "contact_id": { "nullable": true, "description": "The borrower it belongs to, when the file names one.", "type": "string" }, "contact_name": { "nullable": true, "description": "The full name of that borrower, for display. Null when `contact_id` is null.", "type": "string" }, "file_name": { "type": "string", "description": "Original filename as uploaded." }, "display_name": { "nullable": true, "description": "The name brokers see in BrokerPlus. A broker can type it, or BrokerPlus makes it from the document type. Null until either occurs.", "type": "string" }, "file_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs. `GET /v1/document-types` lists the codes." }, "document_type_label": { "nullable": true, "description": "The readable name of `document_type`, e.g. `Paystub`. Null for `unknown` and for a custom type.", "type": "string" }, "classification_status": { "type": "string", "description": "`pending`, `classified`, or `needs_review`. New values can appear as the classifier grows." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "Where the document is on the deal's document board. `pending` and `review` both mean received and not yet checked. `verified` means checked and ready to go to a lender." }, "verified": { "type": "boolean", "description": "`true` when `stage` is `verified`. Filter the list with `verified=true`." }, "folder": { "nullable": true, "description": "The folder of a verified document, e.g. `income` or `down_payment`. `unsorted` means a broker has not filed it yet. Null when the document is not verified.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] }, "uploaded_via": { "type": "string", "enum": [ "portal", "email", "manual", "api", "assembled", "generated" ], "description": "How it arrived: `manual` (a broker), `api` (this API), `email` (an email attachment), `portal` (the client), `generated` or `assembled` (made in BrokerPlus)." }, "uploaded_by_user_id": { "nullable": true, "description": "The broker who added the file. Null when the client, an email, or BrokerPlus added it.", "type": "string" }, "uploaded_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments when a document is replaced rather than added." }, "excluded_from_submission": { "type": "boolean", "description": "True when the broker has marked the file as one that does not go to a lender, e.g. a duplicate or a working copy. A new lender submission leaves it out unless the broker picks it." }, "created_at": { "type": "string", "description": "When the document was uploaded." }, "updated_at": { "type": "string", "description": "Last change to its metadata or classification." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "file_name", "display_name", "file_type", "file_size", "document_type", "document_type_label", "classification_status", "stage", "verified", "folder", "uploaded_via", "uploaded_by_user_id", "uploaded_by_name", "version", "excluded_from_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`contact_id` is not an applicant on the deal, for example a realtor or a contact from another deal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDocument", "summary": "Delete a document", "description": "Deletes the file from the deal and from storage. You cannot undo this. When the client sent the file through the client hub, the client's copy goes too.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/documents/{id}/stage": { "post": { "operationId": "moveDocumentStage", "summary": "Move a document to another tray", "description": "The same move as a drag on the deal's document board. Send `stage` `verified` to mark the document checked and ready to go to a lender, with a `folder` to file it. Send the same `stage` with another `folder` to move a verified document between folders. Nothing goes to the client. To reject a document and ask the client for a new copy, use BrokerPlus: that request emails the client.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "The tray to move the document to. `verified` marks it checked and ready to go to a lender. `pending` and `review` take the check back." }, "folder": { "description": "The folder for a verified document, for example `income`. Only with `stage` `verified`. Without it, the document goes to `unsorted`, which means a broker has not filed it yet.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] } }, "required": [ "stage" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document", "description": "The type of this record. Always `document`.", "type": "string", "enum": [ "document" ] }, "id": { "type": "string", "description": "Stable identifier for the document." }, "deal_id": { "type": "string", "description": "The deal this document is filed under." }, "contact_id": { "nullable": true, "description": "The borrower it belongs to, when the file names one.", "type": "string" }, "contact_name": { "nullable": true, "description": "The full name of that borrower, for display. Null when `contact_id` is null.", "type": "string" }, "file_name": { "type": "string", "description": "Original filename as uploaded." }, "display_name": { "nullable": true, "description": "The name brokers see in BrokerPlus. A broker can type it, or BrokerPlus makes it from the document type. Null until either occurs.", "type": "string" }, "file_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs. `GET /v1/document-types` lists the codes." }, "document_type_label": { "nullable": true, "description": "The readable name of `document_type`, e.g. `Paystub`. Null for `unknown` and for a custom type.", "type": "string" }, "classification_status": { "type": "string", "description": "`pending`, `classified`, or `needs_review`. New values can appear as the classifier grows." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "Where the document is on the deal's document board. `pending` and `review` both mean received and not yet checked. `verified` means checked and ready to go to a lender." }, "verified": { "type": "boolean", "description": "`true` when `stage` is `verified`. Filter the list with `verified=true`." }, "folder": { "nullable": true, "description": "The folder of a verified document, e.g. `income` or `down_payment`. `unsorted` means a broker has not filed it yet. Null when the document is not verified.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] }, "uploaded_via": { "type": "string", "enum": [ "portal", "email", "manual", "api", "assembled", "generated" ], "description": "How it arrived: `manual` (a broker), `api` (this API), `email` (an email attachment), `portal` (the client), `generated` or `assembled` (made in BrokerPlus)." }, "uploaded_by_user_id": { "nullable": true, "description": "The broker who added the file. Null when the client, an email, or BrokerPlus added it.", "type": "string" }, "uploaded_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Increments when a document is replaced rather than added." }, "excluded_from_submission": { "type": "boolean", "description": "True when the broker has marked the file as one that does not go to a lender, e.g. a duplicate or a working copy. A new lender submission leaves it out unless the broker picks it." }, "created_at": { "type": "string", "description": "When the document was uploaded." }, "updated_at": { "type": "string", "description": "Last change to its metadata or classification." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "file_name", "display_name", "file_type", "file_size", "document_type", "document_type_label", "classification_status", "stage", "verified", "folder", "uploaded_via", "uploaded_by_user_id", "uploaded_by_name", "version", "excluded_from_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/documents/{id}/notes": { "get": { "operationId": "listDocumentNotes", "summary": "List the notes on a document", "description": "The notes brokers wrote on this document in its preview in BrokerPlus, newest first. Replies are in the list too, with `parent_id` set. Only the broker's team sees these notes. A client never does.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "document_note", "description": "The type of this record. Always `document_note`.", "type": "string", "enum": [ "document_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "document_id": { "type": "string", "description": "The document the note is on." }, "deal_id": { "nullable": true, "description": "The deal the document is on.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "document_id", "deal_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDocumentNote", "summary": "Write a note on a document", "description": "Adds a note to the document, as the notes panel of the document preview does. A teammate mentioned in the body is told, the same as in BrokerPlus. Nothing reaches a client. Supports `Idempotency-Key`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." }, "parent_id": { "description": "Reply to this note. Must belong to the same record, and cannot itself be a reply.", "nullable": true, "type": "string" } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document_note", "description": "The type of this record. Always `document_note`.", "type": "string", "enum": [ "document_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "document_id": { "type": "string", "description": "The document the note is on." }, "deal_id": { "nullable": true, "description": "The deal the document is on.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "document_id", "deal_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body has no visible content, or `parent_id` is a reply (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The document or the parent note does not exist, or the broker cannot change the document (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/documents/{id}/notes/{noteId}": { "patch": { "operationId": "updateDocumentNote", "summary": "Change a note on a document", "description": "Changes the body of a note. Only the broker who wrote the note can change it.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The new note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "document_note", "description": "The type of this record. Always `document_note`.", "type": "string", "enum": [ "document_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "document_id": { "type": "string", "description": "The document the note is on." }, "deal_id": { "nullable": true, "description": "The deal the document is on.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." } }, "required": [ "object", "id", "document_id", "deal_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No note with this id is on the document, or the key's broker did not write it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDocumentNote", "summary": "Delete a note on a document", "description": "Deletes the note and its replies. You cannot undo this. Only the broker who wrote the note can delete it.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No note with this id is on the document, or the key's broker did not write it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/conditions/{id}": { "get": { "operationId": "getCondition", "summary": "Retrieve a condition", "description": "A single condition by id.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCondition", "summary": "Update a condition", "description": "Move a condition to a new status, or change its due date. `lender_status` is not writable: it is the lender's own answer and is refreshed from them, so a value written here would be overwritten and would meanwhile claim the lender accepted something it never saw.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Where the condition stands with your team. Setting it to `satisfied` stamps `satisfied_at`.", "type": "string", "enum": [ "outstanding", "needs_review", "submitted", "satisfied", "waived", "rejected" ] }, "due_date": { "description": "ISO 8601 date the condition is due, or null to clear it.", "nullable": true, "type": "string" }, "status_note": { "description": "The team's note on where the condition stands. Send null or an empty string to clear it.", "nullable": true, "type": "string", "maxLength": 2000 }, "assignee_role": { "description": "Who owes the condition. Use `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`, or your own value. Send null to clear it.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 64 }, "assignee_contact_id": { "description": "A contact in your brokerage who owes the condition, e.g. the lawyer. Send null to clear it.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "You must review the lender email extraction in BrokerPlus before you change the condition status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/conditions/{id}/satisfy": { "post": { "operationId": "satisfyCondition", "summary": "Satisfy a condition", "description": "Marks the condition `satisfied` and stamps `satisfied_at`. The task to decide it is completed. Send no body.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "You must review the lender email extraction in BrokerPlus before you change the condition status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/conditions/{id}/waive": { "post": { "operationId": "waiveCondition", "summary": "Waive a condition", "description": "Marks the condition `waived`: it no longer blocks the deal, but it was not satisfied. The task to decide it is completed. Send no body.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "You must review the lender email extraction in BrokerPlus before you change the condition status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/conditions/{id}/documents": { "post": { "operationId": "attachConditionDocuments", "summary": "Attach documents to a condition", "description": "Attaches documents on the deal to the condition as what answers it, as the attach on the deal's Conditions tab does. The documents go to the lender with the condition. A document that is already attached stays attached once. Nothing is sent and the condition's status does not change: satisfy it with `POST /conditions/{id}/satisfy`.", "tags": [ "Conditions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The documents that answer the condition. Each one has to be on the condition's deal: list them with `GET /deals/{id}/documents`. A document that is already attached stays attached." } }, "required": [ "document_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "condition", "description": "The type of this record. Always `condition`.", "type": "string", "enum": [ "condition" ] }, "id": { "type": "string", "description": "Stable identifier for the condition." }, "deal_id": { "type": "string", "description": "The deal this condition is on." }, "submission_id": { "nullable": true, "description": "The lender submission that raised it. Null if broker-added.", "type": "string" }, "source": { "type": "string", "description": "Where it came from, e.g. `lender` or `broker`." }, "title": { "type": "string", "description": "What has to be satisfied, in the lender's or broker's words." }, "description": { "nullable": true, "description": "Longer detail, when the condition carries any.", "type": "string" }, "category": { "type": "string", "description": "Coarse grouping used to sort the checklist, e.g. `income` or `property`." }, "status": { "type": "string", "description": "Broker-owned state: `outstanding`, `satisfied`, or `waived`. This is the one to act on." }, "lender_status": { "nullable": true, "description": "What the lender last reported, refreshed each decision poll. Never broker-edited.", "type": "string" }, "priority": { "type": "string", "description": "`low`, `normal`, or `high`. Drives ordering in the BrokerPlus checklist." }, "due_date": { "nullable": true, "description": "When it is due, if a date was set.", "type": "string" }, "satisfied_at": { "nullable": true, "description": "When it was marked satisfied. Null while outstanding.", "type": "string" }, "auto_satisfied": { "type": "boolean", "description": "True when BrokerPlus satisfied it from an uploaded document, not a broker." }, "assignee_role": { "nullable": true, "description": "Who owes the condition, e.g. `broker`, `borrower`, `lawyer`, `credit_assistant`, `realtor`, `insurer`. A brokerage can use its own value. Null when nobody is assigned.", "type": "string" }, "assignee_contact_id": { "nullable": true, "description": "The contact who owes the condition, when it is a named person. Null when nobody is named.", "type": "string" }, "assignee_contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "lender_condition_name": { "nullable": true, "description": "The lender's own name for the condition, when it differs from `title`. Null on a broker's condition.", "type": "string" }, "plain_title": { "nullable": true, "description": "`title` rewritten in plain language for the client, as BrokerPlus shows it to them. Null until it is written.", "type": "string" }, "plain_description": { "nullable": true, "description": "`description` in plain language for the client.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels on the condition, e.g. the document it asks for. Often empty." }, "needs_review": { "type": "boolean", "description": "True when the condition was read out of a lender's email and a broker has to check it in BrokerPlus. Its status cannot change until they do." }, "status_note": { "nullable": true, "description": "The team's note on where the condition stands, e.g. `Asked for T4s`.", "type": "string" }, "status_note_at": { "nullable": true, "description": "When `status_note` was last written.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was satisfied or waived. Null while outstanding. `satisfied_at` is set on a satisfy only.", "type": "string" }, "satisfied_by_user_id": { "nullable": true, "description": "The broker who satisfied it. Null while outstanding, when waived, or when BrokerPlus satisfied it.", "type": "string" }, "auto_satisfied_document_id": { "nullable": true, "description": "The document that satisfied it, when `auto_satisfied` is true. Read it with `GET /documents/{id}`.", "type": "string" }, "source_communication_id": { "nullable": true, "description": "The email the condition was read from, when it came from a lender's email. Null otherwise.", "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The document's file name, for display." }, "document_type": { "type": "string", "description": "What BrokerPlus classified it as, e.g. `paystub`. `unknown` until classification runs." }, "linked_at": { "type": "string", "description": "When the document was attached to the condition." } }, "required": [ "document_id", "file_name", "document_type", "linked_at" ], "additionalProperties": false }, "description": "The documents attached to the condition as what answers it, oldest first. Attach more with `POST /conditions/{id}/documents`." }, "created_at": { "type": "string", "description": "When the condition was raised." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "submission_id", "source", "title", "description", "category", "status", "lender_status", "priority", "due_date", "satisfied_at", "auto_satisfied", "assignee_role", "assignee_contact_id", "assignee_contact_name", "lender_condition_name", "plain_title", "plain_description", "tags", "needs_review", "status_note", "status_note_at", "resolved_at", "satisfied_by_user_id", "auto_satisfied_document_id", "source_communication_id", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is locked at its stage (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The condition does not exist, or the broker cannot change its deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "A document is not on the condition's deal (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lenders": { "get": { "operationId": "listLenders", "summary": "List lenders", "description": "The lenders this brokerage places business with, from its own catalogue (`source: brokerplus`) and from its connected Finmo account (`source: finmo`). Compensation is deliberately not published. Rate sheets are under `/v1/rate-sheets`.", "tags": [ "Lenders" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "brokerplus", "finmo" ] }, "description": "Only lenders from this source: `brokerplus` or `finmo`." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send `true` to include lenders the brokerage has switched off." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "lender", "description": "The type of this record. Always `lender`.", "type": "string", "enum": [ "lender" ] }, "id": { "type": "string", "description": "Stable identifier for the lender, within this brokerage." }, "source": { "type": "string", "enum": [ "brokerplus", "finmo" ], "description": "`brokerplus` is the brokerage's own lender catalogue. `finmo` is mirrored from the connected Finmo account, and is the lender a Finmo submission names." }, "name": { "type": "string", "description": "Lender name as brokers refer to it. A Finmo lender folds its product line into the name." }, "slug": { "nullable": true, "description": "Machine-readable name. Stable per brokerage - branch on this, not on `name`. Null on a Finmo lender.", "type": "string" }, "is_active": { "type": "boolean", "description": "Whether the brokerage currently places business with them." }, "is_prime": { "type": "boolean", "description": "A-lender. Prime, alternative and private are not mutually exclusive. False on a Finmo lender." }, "is_alternative": { "type": "boolean", "description": "B-lender. False on a Finmo lender." }, "is_private": { "type": "boolean", "description": "Private lender. Drives the private-lender disclosure requirement. False on a Finmo lender." }, "lender_type": { "nullable": true, "description": "Finmo's own classification, e.g. `fx_direct`, `mic`, `credit_union`. Null on a BrokerPlus lender.", "type": "string" }, "website": { "nullable": true, "description": "Lender's site, when one is on file.", "type": "string" }, "contact_email": { "nullable": true, "description": "The lender's contact email, when one is on file. Null on a Finmo lender.", "type": "string" }, "contact_phone": { "nullable": true, "description": "The lender's contact phone, when one is on file. Null on a Finmo lender.", "type": "string" }, "equifax_accredited": { "type": "boolean", "description": "`true` when the lender accepts an Equifax credit report. False on a Finmo lender." }, "transunion_accredited": { "type": "boolean", "description": "`true` when the lender accepts a TransUnion credit report. False on a Finmo lender." }, "cmhc_approved": { "type": "boolean", "description": "`true` when the lender is approved for CMHC-insured mortgages. False on a Finmo lender." }, "under_maintenance": { "type": "boolean", "description": "`true` while Finmo has the lender down for maintenance, so it cannot take a submission for now. `is_active` is false meanwhile. Always false on a BrokerPlus lender." }, "lending_guidelines": { "nullable": true, "description": "The lender's guidelines as Finmo publishes them, in their words. Null on a BrokerPlus lender.", "type": "string" }, "created_at": { "type": "string", "description": "When the lender was added to the brokerage." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "source", "name", "slug", "is_active", "is_prime", "is_alternative", "is_private", "lender_type", "website", "contact_email", "contact_phone", "equifax_accredited", "transunion_accredited", "cmhc_approved", "under_maintenance", "lending_guidelines", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/application": { "get": { "operationId": "getDealApplication", "summary": "Retrieve a deal's mortgage application", "description": "The mortgage record itself: amount, term, amortization, rates and payment, with the figures BrokerPlus calculates from it: the total loan amount, the insurance premium, and the gross debt service, total debt service and loan-to-value ratios. Rates and ratios on this object are PERCENT (`5.25` means 5.25%), not decimal fractions. Every lender-coded field arrives as a `code` plus a readable `label`.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "application", "description": "The type of this record. Always `application`.", "type": "string", "enum": [ "application" ] }, "id": { "type": "string", "description": "Stable identifier for the mortgage application." }, "deal_id": { "type": "string", "description": "The deal it belongs to. One application per deal." }, "loan_amount": { "nullable": true, "description": "Principal, in dollars.", "type": "number" }, "term_months": { "nullable": true, "description": "Term length in months, e.g. 60 for a 5-year term.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "Amortization in months, e.g. 300 for 25 years.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "net_rate": { "nullable": true, "description": "Contract rate as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "qualifying_rate": { "nullable": true, "description": "Stress-test rate as a PERCENT, e.g. `7.25` means 7.25%.", "type": "number" }, "posted_rate": { "nullable": true, "description": "Lender's posted rate as a PERCENT, e.g. `6.79` means 6.79%.", "type": "number" }, "payment_amount": { "nullable": true, "description": "Scheduled payment, in dollars, at `payment_frequency`.", "type": "number" }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the payment is made, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the payment is made, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type." }, "loan_purpose": { "type": "object", "properties": { "code": { "nullable": true, "description": "Why the money is being borrowed, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Why the money is being borrowed, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Loan purpose." }, "mortgage_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of mortgage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of mortgage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage type." }, "purchase_price": { "nullable": true, "description": "Purchase price or estimated value, in dollars.", "type": "number" }, "product_name": { "nullable": true, "description": "The lender product chosen, for display.", "type": "string" }, "maturity_date": { "nullable": true, "description": "When the term ends.", "type": "string" }, "first_payment_date": { "nullable": true, "description": "When the first payment is due.", "type": "string" }, "funding_date": { "nullable": true, "description": "When the mortgage funds or funded.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "When interest adjusts, before the first payment.", "type": "string" }, "mortgage_insurer": { "type": "object", "properties": { "code": { "nullable": true, "description": "The default insurer, e.g. CMHC, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The default insurer, e.g. CMHC, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage insurer." }, "rate_hold_expires_at": { "nullable": true, "description": "When the held rate lapses.", "type": "string" }, "financing_condition_date": { "nullable": true, "description": "When the financing condition on the purchase comes off.", "type": "string" }, "total_loan_amount": { "nullable": true, "description": "The amount the lender is asked to advance, in dollars: `loan_amount` plus `insurance_premium` when the premium is added to the loan. `loan_amount` already holds the premium when it is within one dollar of the purchase price less the down payment plus the premium, or of Finmo's own total. Then this is `loan_amount`, and the loan before the premium is this minus `insurance_premium`. With no property value, a premium on file is added only on a deal that started in Finmo. BrokerPlus calculates it.", "type": "number" }, "insurance_premium": { "nullable": true, "description": "Default insurance premium, in dollars, as BrokerPlus calculates it. A premium rate or amount on file, or Finmo's own split of its total, replaces the calculated one. `null` when the mortgage takes no premium, or when there is no property value to place a premium on file against.", "type": "number" }, "insurance_premium_rate": { "nullable": true, "description": "Premium rate as a PERCENT of the loan before the premium, e.g. `4` means 4%. Not a fraction. That is `loan_amount`, unless `loan_amount` already holds the premium.", "type": "number" }, "insurance_premium_added_to_loan": { "nullable": true, "description": "`true` when the premium is added to the loan, `false` when the borrower pays it at closing. `null` means nobody answered. BrokerPlus then adds it to the loan.", "type": "boolean" }, "gds": { "nullable": true, "description": "Gross debt service ratio as a PERCENT, e.g. `32.5` means 32.5%. BrokerPlus calculates it at `ratio_qualifying_rate` from the included applicants. `null` when the application has no income or no payment to divide.", "type": "number" }, "tds": { "nullable": true, "description": "Total debt service ratio as a PERCENT, e.g. `41.2` means 41.2%. Calculated the same way as `gds`, with the other debts added.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan-to-value ratio as a PERCENT, e.g. `80` means 80%. The value is the lower of the purchase price and the appraised value. On a second or later charge against a home the borrower already owns, it is the combined loan to value: the balance of each charge ahead of the loan is added to it. When the deal cannot say which charge is ahead, it is the loan alone.", "type": "number" }, "ratio_qualifying_rate": { "nullable": true, "description": "The rate as a PERCENT that `gds` and `tds` use. It is never below the minimum qualifying rate, so it can differ from `qualifying_rate`.", "type": "number" }, "rate_capped": { "nullable": true, "description": "`true` when a variable rate has a ceiling. `null` means nobody answered.", "type": "boolean" }, "loan_purpose_renewal": { "nullable": true, "description": "`true` when the mortgage is a renewal. A renewal has no `loan_purpose` code. `null` means nobody answered.", "type": "boolean" }, "loan_purpose_improvements": { "nullable": true, "description": "`true` when the loan also pays for improvements to the property. `null` means nobody answered.", "type": "boolean" }, "improvement_cost": { "nullable": true, "description": "Cost of the improvements, in dollars.", "type": "number" }, "payment_accelerated": { "nullable": true, "description": "`true` when the payments are accelerated. Read it with `payment_frequency`, because the frequency codes have no accelerated value. `null` means nobody answered.", "type": "boolean" }, "insurer_policy_number": { "nullable": true, "description": "The default insurer's certificate or policy number.", "type": "string" }, "label": { "nullable": true, "description": "The broker's own name for this scenario, e.g. `with the co-signer`. `null` when the broker named none.", "type": "string" }, "loan_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of loan, e.g. mortgage or line of credit, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of loan, e.g. mortgage or line of credit, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Loan type." }, "charge_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The charge position on title, e.g. first, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The charge position on title, e.g. first, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Charge type." }, "repayment_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the loan is repaid, e.g. amortizing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the loan is repaid, e.g. amortizing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Repayment type." }, "requested_payment": { "nullable": true, "description": "The payment the borrower asked for, in dollars.", "type": "number" }, "down_payment_override": { "nullable": true, "description": "The down payment the broker typed, in dollars. It can differ from the sum of `downpayments` on `GET /deals/{id}/financials`. `null` means the broker typed none.", "type": "number" }, "legal_and_closing_costs": { "nullable": true, "description": "Legal and closing costs the broker was quoted, in dollars. Refinances and switches only.", "type": "number" }, "type_of_buyer": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of buyer, e.g. first-time buyer, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of buyer, e.g. first-time buyer, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Type of buyer." }, "loan_purpose_additional": { "nullable": true, "description": "More detail on the loan purpose, in the broker's words.", "type": "string" }, "mortgage_classification": { "type": "object", "properties": { "code": { "nullable": true, "description": "The lender's classification of the mortgage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The lender's classification of the mortgage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage classification." }, "product_code": { "nullable": true, "description": "The lender's code for the chosen product. Read it with `product_name`.", "type": "string" }, "rate_compound_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often interest compounds, e.g. semi-annually, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often interest compounds, e.g. semi-annually, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate compounding frequency." }, "lender_classification": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of lender, e.g. bank or credit union, as the origination system states it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of lender, e.g. bank or credit union, as the origination system states it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Lender classification." }, "early_payout_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Whether the mortgage is open, closed, or convertible, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Whether the mortgage is open, closed, or convertible, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Early payout type. It decides whether a prepayment costs anything." }, "capitalize_payout_penalty": { "nullable": true, "description": "`true` when the outgoing lender's payout penalty is added to the new mortgage, `false` when the borrower pays it at closing. Refinances and switches only. `null` means nobody answered.", "type": "boolean" }, "purchase_stage": { "nullable": true, "description": "How far along the purchase is: `not_started`, `looking`, `offer_made`, or `offer_accepted`. `null` means nobody answered.", "type": "string" }, "purchase_timeline": { "nullable": true, "description": "When the borrower expects to buy, in the broker's words.", "type": "string" }, "improvement_description": { "nullable": true, "description": "What the improvements are. Read it with `improvement_cost`.", "type": "string" }, "security_deposit_amount": { "nullable": true, "description": "Deposit paid on the purchase, in dollars.", "type": "number" }, "stated_fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the fee." }, "name": { "type": "string", "description": "The fee name, in the words of the system that sent it." }, "kind": { "type": "string", "description": "The kind of fee as the sending system names it, e.g. `regular`, `sales_tax`, `insurance_premium`, or `value_to_borrower`. Other values can occur." }, "amount": { "type": "number", "description": "Fee amount, in dollars." }, "deducted_from_principal": { "type": "boolean", "description": "`true` when the lender takes the fee from the advance." }, "recorded_at": { "nullable": true, "description": "When the sending system recorded the fee, as an ISO 8601 timestamp.", "type": "string" } }, "required": [ "id", "name", "kind", "amount", "deducted_from_principal", "recorded_at" ], "additionalProperties": false }, "description": "Fees on the deal as the origination system (for example Finmo) states them. BrokerPlus records them and does not change them. Empty when no system sent fees." }, "created_at": { "type": "string", "description": "When the application was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "loan_amount", "term_months", "amortization_months", "net_rate", "qualifying_rate", "posted_rate", "payment_amount", "payment_frequency", "rate_type", "loan_purpose", "mortgage_type", "purchase_price", "product_name", "maturity_date", "first_payment_date", "funding_date", "interest_adjustment_date", "mortgage_insurer", "rate_hold_expires_at", "financing_condition_date", "total_loan_amount", "insurance_premium", "insurance_premium_rate", "insurance_premium_added_to_loan", "gds", "tds", "ltv", "ratio_qualifying_rate", "rate_capped", "loan_purpose_renewal", "loan_purpose_improvements", "improvement_cost", "payment_accelerated", "insurer_policy_number", "label", "loan_type", "charge_type", "repayment_type", "requested_payment", "down_payment_override", "legal_and_closing_costs", "type_of_buyer", "loan_purpose_additional", "mortgage_classification", "product_code", "rate_compound_frequency", "lender_classification", "early_payout_type", "capitalize_payout_penalty", "purchase_stage", "purchase_timeline", "improvement_description", "security_deposit_amount", "stated_fees", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealApplication", "summary": "Update a deal's mortgage application", "description": "Changes the loan amount, rate, rate type, term, amortization, first payment date or financing condition date. Send only the fields to change. Rates are PERCENT (`5.25` means 5.25%). If the deal has no application yet, this creates one.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "loan_amount": { "description": "Principal, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "net_rate": { "description": "Contract rate as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "rate_type": { "description": "Rate type, as the numeric `code` that `rate_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 2, 12, 99 ] }, "term_months": { "description": "Term length in months, e.g. 60 for a 5-year term. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 1200 }, "amortization_months": { "description": "Amortization in months, e.g. 300 for 25 years. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 1200 }, "purchase_price": { "description": "Purchase price or estimated value, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "payment_amount": { "description": "Scheduled payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "payment_frequency": { "description": "Payment frequency, as the numeric `code` that `payment_frequency` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ] }, "payment_accelerated": { "description": "Whether payments are accelerated. Use true with payment_frequency 26 for accelerated bi-weekly or 52 for accelerated weekly. False means regular payments. Send null to clear.", "nullable": true, "type": "boolean" }, "mortgage_insurer": { "description": "Mortgage insurer, as the numeric `code` that `mortgage_insurer` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 99 ] }, "maturity_date": { "description": "When the term ends. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "first_payment_date": { "description": "When the first payment is due. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "interest_adjustment_date": { "description": "When interest adjusts, before the first payment. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "funding_date": { "description": "When the mortgage funds or funded. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "financing_condition_date": { "description": "When the financing condition on the purchase comes off. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "label": { "description": "The broker's own name for this scenario. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "loan_type": { "description": "Loan type, as the numeric `code` that `loan_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 1 ] }, "charge_type": { "description": "Charge type, as the numeric `code` that `charge_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 99 ] }, "repayment_type": { "description": "Repayment type, as the numeric `code` that `repayment_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "requested_payment": { "description": "The payment the borrower asked for, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "down_payment_override": { "description": "The down payment the broker states, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "legal_and_closing_costs": { "description": "Legal and closing costs the broker was quoted, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "type_of_buyer": { "description": "Type of buyer, as the numeric `code` that `type_of_buyer` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20 ] }, "loan_purpose_additional": { "description": "More detail on the loan purpose. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 }, "mortgage_classification": { "description": "Mortgage classification, as the numeric `code` that `mortgage_classification` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50 ] }, "rate_compound_frequency": { "description": "Rate compounding frequency, as the numeric `code` that `rate_compound_frequency` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 4, 12 ] }, "lender_classification": { "description": "Lender classification, as the numeric `code` that `lender_classification` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 99 ] }, "early_payout_type": { "description": "Early payout type, as the numeric `code` that `early_payout_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30 ] }, "capitalize_payout_penalty": { "description": "`true` to add the outgoing lender's payout penalty to the new mortgage, `false` when the borrower pays it at closing. Send null to clear.", "nullable": true, "type": "boolean" }, "purchase_stage": { "description": "`not_started`, `looking`, `offer_made`, or `offer_accepted`. Send null to clear.", "nullable": true, "type": "string", "enum": [ "not_started", "looking", "offer_made", "offer_accepted" ] }, "purchase_timeline": { "description": "When the borrower expects to buy. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "improvement_description": { "description": "What the improvements are. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 }, "security_deposit_amount": { "description": "Deposit paid on the purchase, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "application", "description": "The type of this record. Always `application`.", "type": "string", "enum": [ "application" ] }, "id": { "type": "string", "description": "Stable identifier for the mortgage application." }, "deal_id": { "type": "string", "description": "The deal it belongs to. One application per deal." }, "loan_amount": { "nullable": true, "description": "Principal, in dollars.", "type": "number" }, "term_months": { "nullable": true, "description": "Term length in months, e.g. 60 for a 5-year term.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "Amortization in months, e.g. 300 for 25 years.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "net_rate": { "nullable": true, "description": "Contract rate as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "qualifying_rate": { "nullable": true, "description": "Stress-test rate as a PERCENT, e.g. `7.25` means 7.25%.", "type": "number" }, "posted_rate": { "nullable": true, "description": "Lender's posted rate as a PERCENT, e.g. `6.79` means 6.79%.", "type": "number" }, "payment_amount": { "nullable": true, "description": "Scheduled payment, in dollars, at `payment_frequency`.", "type": "number" }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the payment is made, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the payment is made, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type." }, "loan_purpose": { "type": "object", "properties": { "code": { "nullable": true, "description": "Why the money is being borrowed, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Why the money is being borrowed, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Loan purpose." }, "mortgage_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of mortgage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of mortgage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage type." }, "purchase_price": { "nullable": true, "description": "Purchase price or estimated value, in dollars.", "type": "number" }, "product_name": { "nullable": true, "description": "The lender product chosen, for display.", "type": "string" }, "maturity_date": { "nullable": true, "description": "When the term ends.", "type": "string" }, "first_payment_date": { "nullable": true, "description": "When the first payment is due.", "type": "string" }, "funding_date": { "nullable": true, "description": "When the mortgage funds or funded.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "When interest adjusts, before the first payment.", "type": "string" }, "mortgage_insurer": { "type": "object", "properties": { "code": { "nullable": true, "description": "The default insurer, e.g. CMHC, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The default insurer, e.g. CMHC, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage insurer." }, "rate_hold_expires_at": { "nullable": true, "description": "When the held rate lapses.", "type": "string" }, "financing_condition_date": { "nullable": true, "description": "When the financing condition on the purchase comes off.", "type": "string" }, "total_loan_amount": { "nullable": true, "description": "The amount the lender is asked to advance, in dollars: `loan_amount` plus `insurance_premium` when the premium is added to the loan. `loan_amount` already holds the premium when it is within one dollar of the purchase price less the down payment plus the premium, or of Finmo's own total. Then this is `loan_amount`, and the loan before the premium is this minus `insurance_premium`. With no property value, a premium on file is added only on a deal that started in Finmo. BrokerPlus calculates it.", "type": "number" }, "insurance_premium": { "nullable": true, "description": "Default insurance premium, in dollars, as BrokerPlus calculates it. A premium rate or amount on file, or Finmo's own split of its total, replaces the calculated one. `null` when the mortgage takes no premium, or when there is no property value to place a premium on file against.", "type": "number" }, "insurance_premium_rate": { "nullable": true, "description": "Premium rate as a PERCENT of the loan before the premium, e.g. `4` means 4%. Not a fraction. That is `loan_amount`, unless `loan_amount` already holds the premium.", "type": "number" }, "insurance_premium_added_to_loan": { "nullable": true, "description": "`true` when the premium is added to the loan, `false` when the borrower pays it at closing. `null` means nobody answered. BrokerPlus then adds it to the loan.", "type": "boolean" }, "gds": { "nullable": true, "description": "Gross debt service ratio as a PERCENT, e.g. `32.5` means 32.5%. BrokerPlus calculates it at `ratio_qualifying_rate` from the included applicants. `null` when the application has no income or no payment to divide.", "type": "number" }, "tds": { "nullable": true, "description": "Total debt service ratio as a PERCENT, e.g. `41.2` means 41.2%. Calculated the same way as `gds`, with the other debts added.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan-to-value ratio as a PERCENT, e.g. `80` means 80%. The value is the lower of the purchase price and the appraised value. On a second or later charge against a home the borrower already owns, it is the combined loan to value: the balance of each charge ahead of the loan is added to it. When the deal cannot say which charge is ahead, it is the loan alone.", "type": "number" }, "ratio_qualifying_rate": { "nullable": true, "description": "The rate as a PERCENT that `gds` and `tds` use. It is never below the minimum qualifying rate, so it can differ from `qualifying_rate`.", "type": "number" }, "rate_capped": { "nullable": true, "description": "`true` when a variable rate has a ceiling. `null` means nobody answered.", "type": "boolean" }, "loan_purpose_renewal": { "nullable": true, "description": "`true` when the mortgage is a renewal. A renewal has no `loan_purpose` code. `null` means nobody answered.", "type": "boolean" }, "loan_purpose_improvements": { "nullable": true, "description": "`true` when the loan also pays for improvements to the property. `null` means nobody answered.", "type": "boolean" }, "improvement_cost": { "nullable": true, "description": "Cost of the improvements, in dollars.", "type": "number" }, "payment_accelerated": { "nullable": true, "description": "`true` when the payments are accelerated. Read it with `payment_frequency`, because the frequency codes have no accelerated value. `null` means nobody answered.", "type": "boolean" }, "insurer_policy_number": { "nullable": true, "description": "The default insurer's certificate or policy number.", "type": "string" }, "label": { "nullable": true, "description": "The broker's own name for this scenario, e.g. `with the co-signer`. `null` when the broker named none.", "type": "string" }, "loan_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of loan, e.g. mortgage or line of credit, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of loan, e.g. mortgage or line of credit, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Loan type." }, "charge_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The charge position on title, e.g. first, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The charge position on title, e.g. first, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Charge type." }, "repayment_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the loan is repaid, e.g. amortizing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the loan is repaid, e.g. amortizing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Repayment type." }, "requested_payment": { "nullable": true, "description": "The payment the borrower asked for, in dollars.", "type": "number" }, "down_payment_override": { "nullable": true, "description": "The down payment the broker typed, in dollars. It can differ from the sum of `downpayments` on `GET /deals/{id}/financials`. `null` means the broker typed none.", "type": "number" }, "legal_and_closing_costs": { "nullable": true, "description": "Legal and closing costs the broker was quoted, in dollars. Refinances and switches only.", "type": "number" }, "type_of_buyer": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of buyer, e.g. first-time buyer, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of buyer, e.g. first-time buyer, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Type of buyer." }, "loan_purpose_additional": { "nullable": true, "description": "More detail on the loan purpose, in the broker's words.", "type": "string" }, "mortgage_classification": { "type": "object", "properties": { "code": { "nullable": true, "description": "The lender's classification of the mortgage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The lender's classification of the mortgage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Mortgage classification." }, "product_code": { "nullable": true, "description": "The lender's code for the chosen product. Read it with `product_name`.", "type": "string" }, "rate_compound_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often interest compounds, e.g. semi-annually, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often interest compounds, e.g. semi-annually, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate compounding frequency." }, "lender_classification": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of lender, e.g. bank or credit union, as the origination system states it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of lender, e.g. bank or credit union, as the origination system states it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Lender classification." }, "early_payout_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Whether the mortgage is open, closed, or convertible, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Whether the mortgage is open, closed, or convertible, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Early payout type. It decides whether a prepayment costs anything." }, "capitalize_payout_penalty": { "nullable": true, "description": "`true` when the outgoing lender's payout penalty is added to the new mortgage, `false` when the borrower pays it at closing. Refinances and switches only. `null` means nobody answered.", "type": "boolean" }, "purchase_stage": { "nullable": true, "description": "How far along the purchase is: `not_started`, `looking`, `offer_made`, or `offer_accepted`. `null` means nobody answered.", "type": "string" }, "purchase_timeline": { "nullable": true, "description": "When the borrower expects to buy, in the broker's words.", "type": "string" }, "improvement_description": { "nullable": true, "description": "What the improvements are. Read it with `improvement_cost`.", "type": "string" }, "security_deposit_amount": { "nullable": true, "description": "Deposit paid on the purchase, in dollars.", "type": "number" }, "stated_fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the fee." }, "name": { "type": "string", "description": "The fee name, in the words of the system that sent it." }, "kind": { "type": "string", "description": "The kind of fee as the sending system names it, e.g. `regular`, `sales_tax`, `insurance_premium`, or `value_to_borrower`. Other values can occur." }, "amount": { "type": "number", "description": "Fee amount, in dollars." }, "deducted_from_principal": { "type": "boolean", "description": "`true` when the lender takes the fee from the advance." }, "recorded_at": { "nullable": true, "description": "When the sending system recorded the fee, as an ISO 8601 timestamp.", "type": "string" } }, "required": [ "id", "name", "kind", "amount", "deducted_from_principal", "recorded_at" ], "additionalProperties": false }, "description": "Fees on the deal as the origination system (for example Finmo) states them. BrokerPlus records them and does not change them. Empty when no system sent fees." }, "created_at": { "type": "string", "description": "When the application was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "loan_amount", "term_months", "amortization_months", "net_rate", "qualifying_rate", "posted_rate", "payment_amount", "payment_frequency", "rate_type", "loan_purpose", "mortgage_type", "purchase_price", "product_name", "maturity_date", "first_payment_date", "funding_date", "interest_adjustment_date", "mortgage_insurer", "rate_hold_expires_at", "financing_condition_date", "total_loan_amount", "insurance_premium", "insurance_premium_rate", "insurance_premium_added_to_loan", "gds", "tds", "ltv", "ratio_qualifying_rate", "rate_capped", "loan_purpose_renewal", "loan_purpose_improvements", "improvement_cost", "payment_accelerated", "insurer_policy_number", "label", "loan_type", "charge_type", "repayment_type", "requested_payment", "down_payment_override", "legal_and_closing_costs", "type_of_buyer", "loan_purpose_additional", "mortgage_classification", "product_code", "rate_compound_frequency", "lender_classification", "early_payout_type", "capitalize_payout_penalty", "purchase_stage", "purchase_timeline", "improvement_description", "security_deposit_amount", "stated_fees", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/property": { "get": { "operationId": "getDealProperty", "summary": "Retrieve a deal's subject property", "description": "The property being mortgaged: address components, structure, occupancy and carrying costs. The address is returned as parts rather than one line, because that is what the lender submission carries.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "property", "description": "The type of this record. Always `property`.", "type": "string", "enum": [ "property" ] }, "id": { "type": "string", "description": "Stable identifier for the property." }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "property_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Structure type, e.g. detached, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Structure type, e.g. detached, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property type." }, "occupancy_purpose": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the property is used for, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the property is used for, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupancy purpose." }, "occupancy_type": { "nullable": true, "description": "`owner_occupied`, `partial_owner_occupied`, `rental`, `tenant`, or `none`.", "type": "string" }, "year_built": { "nullable": true, "description": "Year of construction.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "number_of_units": { "nullable": true, "description": "Total units in the building.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "annual_tax_amount": { "nullable": true, "description": "Annual property tax, in dollars.", "type": "number" }, "annual_condo_fees": { "nullable": true, "description": "Annual condo fees, in dollars.", "type": "number" }, "annual_ground_rent": { "nullable": true, "description": "Annual ground rent on leasehold land, in dollars.", "type": "number" }, "annual_heating_amount": { "nullable": true, "description": "Annual heating cost, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Gross annual rent, for a rental or partial rental.", "type": "number" }, "mls_number": { "nullable": true, "description": "MLS listing number, when the property is listed.", "type": "string" }, "appraised_value": { "nullable": true, "description": "Appraised value, in dollars.", "type": "number" }, "appraisal_date": { "nullable": true, "description": "When the appraisal was done.", "type": "string" }, "lending_value_basis": { "nullable": true, "description": "Which value the file's own system lends against, when the file names one. On a refinance, switch or renewal, `ltv` is worked out on that value while the deal holds it. A purchase, and a null here, mean the lower of the purchase price and the appraised value.", "type": "string", "enum": [ "price", "estimate", "appraisal" ] }, "estimated_value": { "nullable": true, "description": "The property's estimated value, in dollars, when the file states one beside a purchase price.", "type": "number" }, "property_description_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of dwelling, e.g. a townhouse, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of dwelling, e.g. a townhouse, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property description." }, "property_usage_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the property is used, e.g. residential, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the property is used, e.g. residential, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property usage." }, "zoning_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the land is zoned, e.g. residential, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the land is zoned, e.g. residential, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Zoning." }, "construction_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "New or existing construction, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "New or existing construction, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Construction type." }, "heating_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the property is heated, e.g. forced air, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the property is heated, e.g. forced air, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Heating type." }, "parking_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Parking, e.g. a garage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Parking, e.g. a garage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Parking type." }, "water_supply_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Where the water comes from, e.g. municipal, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Where the water comes from, e.g. municipal, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Water supply." }, "water_waste_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Where waste water goes, e.g. a septic system, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Where waste water goes, e.g. a septic system, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Waste water." }, "tenure": { "nullable": true, "description": "How the property is held, e.g. freehold, as the origination system states it.", "type": "string" }, "property_size": { "nullable": true, "description": "Living area, in `property_size_units`.", "type": "number" }, "property_size_units": { "type": "object", "properties": { "code": { "nullable": true, "description": "The unit `property_size` is in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The unit `property_size` is in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property size units." }, "lot_size": { "nullable": true, "description": "Lot area, in `lot_size_units`.", "type": "number" }, "lot_size_units": { "type": "object", "properties": { "code": { "nullable": true, "description": "The unit `lot_size` is in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The unit `lot_size` is in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Lot size units." }, "environmental_hazard": { "nullable": true, "description": "`true` when the property has an environmental hazard. `null` means nobody answered.", "type": "boolean" }, "new_property": { "nullable": true, "description": "`true` when the property is new. `null` means nobody answered.", "type": "boolean" }, "mls_listed": { "nullable": true, "description": "`true` when the property is listed on MLS. `null` means nobody answered.", "type": "boolean" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts toward qualifying, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "condo_fee_tds_pct": { "nullable": true, "description": "The share of the condo fee that counts toward the total debt service ratio, as a PERCENT from 0 to 100. `null` counts the whole fee.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "condo_fees_include_heating": { "type": "boolean", "description": "`true` when the condo fee already covers heat." }, "include_expenses_in_tds": { "type": "boolean", "description": "`false` leaves property tax, heat and the condo fee out of the housing cost, for lenders that allow it." }, "annual_tax_estimated": { "nullable": true, "description": "`true` when `annual_tax_amount` is an estimate. `null` means nobody said.", "type": "boolean" }, "tax_year": { "nullable": true, "description": "The year `annual_tax_amount` is for.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxes_paid_by": { "type": "object", "properties": { "code": { "nullable": true, "description": "Who pays the property tax, e.g. the lender, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Who pays the property tax, e.g. the lender, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Taxes paid by." }, "original_purchase_price": { "nullable": true, "description": "What the borrower paid for the property, in dollars.", "type": "number" }, "original_purchase_date": { "nullable": true, "description": "When the borrower bought the property.", "type": "string" }, "monthly_hydro_costs": { "nullable": true, "description": "Monthly hydro cost, in dollars.", "type": "number" }, "monthly_insurance_costs": { "nullable": true, "description": "Monthly insurance cost, in dollars.", "type": "number" }, "monthly_management_costs": { "nullable": true, "description": "Monthly property management cost, in dollars.", "type": "number" }, "monthly_repairs_costs": { "nullable": true, "description": "Monthly repairs cost, in dollars.", "type": "number" }, "monthly_interest_costs": { "nullable": true, "description": "Monthly interest cost, in dollars.", "type": "number" }, "monthly_other_costs": { "nullable": true, "description": "Other monthly operating costs, in dollars.", "type": "number" }, "monthly_fees_offset": { "nullable": true, "description": "Dollars of the monthly condo fee left out of the ratios. Separate from `condo_fee_tds_pct`.", "type": "number" }, "legal_description": { "nullable": true, "description": "The legal description of the land.", "type": "string" }, "legal_pin": { "nullable": true, "description": "The land registry's property identification number (PIN).", "type": "string" } }, "required": [ "object", "id", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "property_type", "occupancy_purpose", "occupancy_type", "year_built", "number_of_units", "annual_tax_amount", "annual_condo_fees", "annual_ground_rent", "annual_heating_amount", "annual_gross_rental_income", "mls_number", "appraised_value", "appraisal_date", "lending_value_basis", "estimated_value", "property_description_type", "property_usage_type", "zoning_type", "construction_type", "heating_type", "parking_type", "water_supply_type", "water_waste_type", "tenure", "property_size", "property_size_units", "lot_size", "lot_size_units", "environmental_hazard", "new_property", "mls_listed", "rental_offset_pct", "rental_calc_type", "condo_fee_tds_pct", "condo_fees_include_heating", "include_expenses_in_tds", "annual_tax_estimated", "tax_year", "taxes_paid_by", "original_purchase_price", "original_purchase_date", "monthly_hydro_costs", "monthly_insurance_costs", "monthly_management_costs", "monthly_repairs_costs", "monthly_interest_costs", "monthly_other_costs", "monthly_fees_offset", "legal_description", "legal_pin" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealProperty", "summary": "Update a deal's subject property address", "description": "Changes the address of the property being mortgaged. Send only the parts to change. Street type, street direction and province take the numeric `code` that the read returns. If the deal has no property yet, this creates one.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unit_number": { "description": "Unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_number": { "description": "Street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_name": { "description": "Street name, without the type or direction. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "street_type": { "description": "Street type, as the numeric `code` that `street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "street_direction": { "description": "Street direction, as the numeric `code` that `street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "city": { "description": "City or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "province": { "description": "Province, as the numeric `code` that `province` returns on read, or as the two-letter code, e.g. `ON`. Send null to clear.", "nullable": true, "anyOf": [ { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] } ] }, "postal_code": { "description": "Postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "occupancy_type": { "description": "Who lives in the property. One of the `occupancy_type` values on read. Send null to clear.", "nullable": true, "type": "string", "enum": [ "owner_occupied", "partial_owner_occupied", "rental", "tenant", "none" ] }, "occupancy_purpose": { "description": "Occupancy purpose, as the numeric `code` that `occupancy_purpose` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 4, 5 ] }, "property_description_type": { "description": "Property description, as the numeric `code` that `property_description_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 99 ] }, "property_usage_type": { "description": "Property usage, as the numeric `code` that `property_usage_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 5, 6, 7, 8, 9, 10, 11, 12, 90 ] }, "zoning_type": { "description": "Zoning, as the numeric `code` that `zoning_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 99 ] }, "construction_type": { "description": "Construction type, as the numeric `code` that `construction_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 99 ] }, "heating_type": { "description": "Heating type, as the numeric `code` that `heating_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4 ] }, "parking_type": { "description": "Parking type, as the numeric `code` that `parking_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] }, "water_supply_type": { "description": "Water supply, as the numeric `code` that `water_supply_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 99 ] }, "water_waste_type": { "description": "Waste water, as the numeric `code` that `water_waste_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 99 ] }, "property_size": { "description": "Living area, in `property_size_units`. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "property_size_units": { "description": "Property size units, as the numeric `code` that `property_size_units` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "lot_size": { "description": "Lot area, in `lot_size_units`. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "lot_size_units": { "description": "Lot size units, as the numeric `code` that `lot_size_units` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "environmental_hazard": { "description": "`true` when the property has an environmental hazard. Send null to clear.", "nullable": true, "type": "boolean" }, "new_property": { "description": "`true` when the property is new. Send null to clear.", "nullable": true, "type": "boolean" }, "mls_listed": { "description": "`true` when the property is listed on MLS. Send null to clear.", "nullable": true, "type": "boolean" }, "rental_offset_pct": { "description": "The share of rent that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "rental_calc_type": { "description": "Rental calculation method, as the numeric `code` that `rental_calc_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "condo_fee_tds_pct": { "description": "The share of the condo fee that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "condo_fees_include_heating": { "description": "`true` when the condo fee already covers heat.", "type": "boolean" }, "include_expenses_in_tds": { "description": "`false` leaves property tax, heat and the condo fee out of the housing cost.", "type": "boolean" }, "annual_tax_estimated": { "description": "`true` when the property tax figure is an estimate. Send null to clear.", "nullable": true, "type": "boolean" }, "tax_year": { "description": "The year the tax figure is for. Send null to clear.", "nullable": true, "type": "integer", "minimum": 1900, "maximum": 2200 }, "taxes_paid_by": { "description": "Taxes paid by, as the numeric `code` that `taxes_paid_by` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "original_purchase_price": { "description": "What the borrower paid for the property, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "original_purchase_date": { "description": "When the borrower bought the property. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "monthly_hydro_costs": { "description": "Monthly hydro cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_insurance_costs": { "description": "Monthly insurance cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_management_costs": { "description": "Monthly property management cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_repairs_costs": { "description": "Monthly repairs cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_interest_costs": { "description": "Monthly interest cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_other_costs": { "description": "Other monthly operating costs, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_fees_offset": { "description": "Monthly condo fee left out of the ratios, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "legal_description": { "description": "The legal description of the land. Send null to clear.", "nullable": true, "type": "string", "maxLength": 2000 }, "legal_pin": { "description": "The land registry's PIN. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "property", "description": "The type of this record. Always `property`.", "type": "string", "enum": [ "property" ] }, "id": { "type": "string", "description": "Stable identifier for the property." }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "property_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Structure type, e.g. detached, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Structure type, e.g. detached, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property type." }, "occupancy_purpose": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the property is used for, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the property is used for, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupancy purpose." }, "occupancy_type": { "nullable": true, "description": "`owner_occupied`, `partial_owner_occupied`, `rental`, `tenant`, or `none`.", "type": "string" }, "year_built": { "nullable": true, "description": "Year of construction.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "number_of_units": { "nullable": true, "description": "Total units in the building.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "annual_tax_amount": { "nullable": true, "description": "Annual property tax, in dollars.", "type": "number" }, "annual_condo_fees": { "nullable": true, "description": "Annual condo fees, in dollars.", "type": "number" }, "annual_ground_rent": { "nullable": true, "description": "Annual ground rent on leasehold land, in dollars.", "type": "number" }, "annual_heating_amount": { "nullable": true, "description": "Annual heating cost, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Gross annual rent, for a rental or partial rental.", "type": "number" }, "mls_number": { "nullable": true, "description": "MLS listing number, when the property is listed.", "type": "string" }, "appraised_value": { "nullable": true, "description": "Appraised value, in dollars.", "type": "number" }, "appraisal_date": { "nullable": true, "description": "When the appraisal was done.", "type": "string" }, "lending_value_basis": { "nullable": true, "description": "Which value the file's own system lends against, when the file names one. On a refinance, switch or renewal, `ltv` is worked out on that value while the deal holds it. A purchase, and a null here, mean the lower of the purchase price and the appraised value.", "type": "string", "enum": [ "price", "estimate", "appraisal" ] }, "estimated_value": { "nullable": true, "description": "The property's estimated value, in dollars, when the file states one beside a purchase price.", "type": "number" }, "property_description_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The kind of dwelling, e.g. a townhouse, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The kind of dwelling, e.g. a townhouse, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property description." }, "property_usage_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the property is used, e.g. residential, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the property is used, e.g. residential, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property usage." }, "zoning_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the land is zoned, e.g. residential, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the land is zoned, e.g. residential, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Zoning." }, "construction_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "New or existing construction, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "New or existing construction, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Construction type." }, "heating_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the property is heated, e.g. forced air, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the property is heated, e.g. forced air, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Heating type." }, "parking_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Parking, e.g. a garage, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Parking, e.g. a garage, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Parking type." }, "water_supply_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Where the water comes from, e.g. municipal, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Where the water comes from, e.g. municipal, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Water supply." }, "water_waste_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Where waste water goes, e.g. a septic system, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Where waste water goes, e.g. a septic system, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Waste water." }, "tenure": { "nullable": true, "description": "How the property is held, e.g. freehold, as the origination system states it.", "type": "string" }, "property_size": { "nullable": true, "description": "Living area, in `property_size_units`.", "type": "number" }, "property_size_units": { "type": "object", "properties": { "code": { "nullable": true, "description": "The unit `property_size` is in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The unit `property_size` is in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Property size units." }, "lot_size": { "nullable": true, "description": "Lot area, in `lot_size_units`.", "type": "number" }, "lot_size_units": { "type": "object", "properties": { "code": { "nullable": true, "description": "The unit `lot_size` is in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The unit `lot_size` is in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Lot size units." }, "environmental_hazard": { "nullable": true, "description": "`true` when the property has an environmental hazard. `null` means nobody answered.", "type": "boolean" }, "new_property": { "nullable": true, "description": "`true` when the property is new. `null` means nobody answered.", "type": "boolean" }, "mls_listed": { "nullable": true, "description": "`true` when the property is listed on MLS. `null` means nobody answered.", "type": "boolean" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts toward qualifying, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "condo_fee_tds_pct": { "nullable": true, "description": "The share of the condo fee that counts toward the total debt service ratio, as a PERCENT from 0 to 100. `null` counts the whole fee.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "condo_fees_include_heating": { "type": "boolean", "description": "`true` when the condo fee already covers heat." }, "include_expenses_in_tds": { "type": "boolean", "description": "`false` leaves property tax, heat and the condo fee out of the housing cost, for lenders that allow it." }, "annual_tax_estimated": { "nullable": true, "description": "`true` when `annual_tax_amount` is an estimate. `null` means nobody said.", "type": "boolean" }, "tax_year": { "nullable": true, "description": "The year `annual_tax_amount` is for.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxes_paid_by": { "type": "object", "properties": { "code": { "nullable": true, "description": "Who pays the property tax, e.g. the lender, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Who pays the property tax, e.g. the lender, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Taxes paid by." }, "original_purchase_price": { "nullable": true, "description": "What the borrower paid for the property, in dollars.", "type": "number" }, "original_purchase_date": { "nullable": true, "description": "When the borrower bought the property.", "type": "string" }, "monthly_hydro_costs": { "nullable": true, "description": "Monthly hydro cost, in dollars.", "type": "number" }, "monthly_insurance_costs": { "nullable": true, "description": "Monthly insurance cost, in dollars.", "type": "number" }, "monthly_management_costs": { "nullable": true, "description": "Monthly property management cost, in dollars.", "type": "number" }, "monthly_repairs_costs": { "nullable": true, "description": "Monthly repairs cost, in dollars.", "type": "number" }, "monthly_interest_costs": { "nullable": true, "description": "Monthly interest cost, in dollars.", "type": "number" }, "monthly_other_costs": { "nullable": true, "description": "Other monthly operating costs, in dollars.", "type": "number" }, "monthly_fees_offset": { "nullable": true, "description": "Dollars of the monthly condo fee left out of the ratios. Separate from `condo_fee_tds_pct`.", "type": "number" }, "legal_description": { "nullable": true, "description": "The legal description of the land.", "type": "string" }, "legal_pin": { "nullable": true, "description": "The land registry's property identification number (PIN).", "type": "string" } }, "required": [ "object", "id", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "property_type", "occupancy_purpose", "occupancy_type", "year_built", "number_of_units", "annual_tax_amount", "annual_condo_fees", "annual_ground_rent", "annual_heating_amount", "annual_gross_rental_income", "mls_number", "appraised_value", "appraisal_date", "lending_value_basis", "estimated_value", "property_description_type", "property_usage_type", "zoning_type", "construction_type", "heating_type", "parking_type", "water_supply_type", "water_waste_type", "tenure", "property_size", "property_size_units", "lot_size", "lot_size_units", "environmental_hazard", "new_property", "mls_listed", "rental_offset_pct", "rental_calc_type", "condo_fee_tds_pct", "condo_fees_include_heating", "include_expenses_in_tds", "annual_tax_estimated", "tax_year", "taxes_paid_by", "original_purchase_price", "original_purchase_date", "monthly_hydro_costs", "monthly_insurance_costs", "monthly_management_costs", "monthly_repairs_costs", "monthly_interest_costs", "monthly_other_costs", "monthly_fees_offset", "legal_description", "legal_pin" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/credit-notes": { "get": { "operationId": "listDealCreditNotes", "summary": "List a deal's credit notes", "description": "The broker's own notes on the credit of the people on the deal, one per person, most recently changed first. This is what the broker wrote, not a credit report: no credit score or bureau data is returned.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "credit_note", "description": "The type of this record. Always `credit_note`.", "type": "string", "enum": [ "credit_note" ] }, "id": { "type": "string", "description": "Stable identifier for the credit note." }, "deal_id": { "type": "string", "description": "The deal the note is on." }, "contact_id": { "type": "string", "description": "The person on the deal whose credit the note is about." }, "contact_name": { "nullable": true, "description": "That person's name, for display.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own words about the person's credit. Null when the broker wrote none.", "type": "string" }, "recorded_by_user_id": { "nullable": true, "description": "The broker who last saved the note.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "When the note last changed." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "body", "recorded_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/credit-notes/{contactId}": { "patch": { "operationId": "updateDealCreditNote", "summary": "Write a credit note", "description": "Writes the broker's note on the credit of a person on the deal, as the credit panel on the deal does. The first write creates the note. A score the broker entered in BrokerPlus is kept as it is.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "nullable": true, "description": "The broker's note on the person's credit, up to 4000 characters. Send null or an empty string to clear it.", "type": "string", "maxLength": 4000 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "credit_note", "description": "The type of this record. Always `credit_note`.", "type": "string", "enum": [ "credit_note" ] }, "id": { "type": "string", "description": "Stable identifier for the credit note." }, "deal_id": { "type": "string", "description": "The deal the note is on." }, "contact_id": { "type": "string", "description": "The person on the deal whose credit the note is about." }, "contact_name": { "nullable": true, "description": "That person's name, for display.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own words about the person's credit. Null when the broker wrote none.", "type": "string" }, "recorded_by_user_id": { "nullable": true, "description": "The broker who last saved the note.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "When the note last changed." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "body", "recorded_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the person is not on it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/life-insurance": { "get": { "operationId": "getDealLifeInsurance", "summary": "Retrieve a deal's creditor life insurance", "description": "The deal's creditor life insurance: whether the broker offered it, what the client said, and where the application is with the insurer. Returns `404` until the broker records an outcome or sends an application.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "life_insurance", "description": "The type of this record. Always `life_insurance`.", "type": "string", "enum": [ "life_insurance" ] }, "id": { "type": "string", "description": "Stable identifier for the deal's creditor life insurance record." }, "deal_id": { "type": "string", "description": "The deal the insurance is for. A deal has at most one." }, "quote_only": { "type": "boolean", "description": "True when the broker asked the insurer for a quote rather than applying." }, "status": { "type": "string", "enum": [ "draft", "quoted", "submitted", "pending", "approved", "declined", "cancelled", "error" ], "description": "Where the application is with the insurer: `draft` until the broker sends it, then `quoted`, `submitted`, `pending`, `approved`, `declined`, `cancelled`, or `error`." }, "status_detail": { "nullable": true, "description": "The insurer's own words on the status, when it gave any.", "type": "string" }, "monthly_premium": { "nullable": true, "description": "The client's monthly premium the insurer quoted, in dollars. Null until there is a quote.", "type": "number" }, "commission_amount": { "nullable": true, "description": "What the broker earns on the policy, in dollars, as the broker entered it. Null until entered.", "type": "number" }, "commission_status": { "nullable": true, "description": "Where that commission is: `pending`, `confirmed`, `paid`, or `clawed_back`. Null until entered.", "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ] }, "commission_paid_at": { "nullable": true, "description": "When the commission was collected. Null until it is.", "type": "string" }, "outcome": { "type": "string", "enum": [ "not_offered", "offered", "accepted", "waived", "referral", "not_supported" ], "description": "Where the conversation with the client landed: `not_offered` until the broker offers it, then `offered`, `accepted`, `waived`, `referral`, or `not_supported`." }, "outcome_at": { "nullable": true, "description": "When the outcome was recorded.", "type": "string" }, "outcome_by_user_id": { "nullable": true, "description": "The broker who recorded the outcome.", "type": "string" }, "outcome_note": { "nullable": true, "description": "The broker's note on the outcome, e.g. why the client waived it.", "type": "string" }, "consent_id": { "nullable": true, "description": "The client's consent that let BrokerPlus send their file to the insurer. Null until it was sent.", "type": "string" }, "certificate_number": { "nullable": true, "description": "The insurer's certificate number, which shows the client is covered. Null until it arrives.", "type": "string" }, "certificate_received_at": { "nullable": true, "description": "When the certificate arrived.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the broker sent the application or quote request.", "type": "string" }, "last_status_at": { "nullable": true, "description": "When the insurer last changed the status.", "type": "string" }, "created_at": { "type": "string", "description": "When the record was created." }, "updated_at": { "type": "string", "description": "When the record last changed." } }, "required": [ "object", "id", "deal_id", "quote_only", "status", "status_detail", "monthly_premium", "commission_amount", "commission_status", "commission_paid_at", "outcome", "outcome_at", "outcome_by_user_id", "outcome_note", "consent_id", "certificate_number", "certificate_received_at", "submitted_at", "last_status_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/life-insurance/outcome": { "post": { "operationId": "recordDealLifeInsuranceOutcome", "summary": "Record the life insurance outcome", "description": "Records where the conversation about creditor life insurance landed with the client, as the deal's insurance panel does. A new outcome replaces the one before. Nothing is sent: when the client accepts, the broker sends the application in BrokerPlus, with the client's consent.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "not_offered", "offered", "accepted", "waived", "referral", "not_supported" ], "description": "Where the conversation with the client landed. `accepted` records that the client wants it: the broker sends the application in BrokerPlus." }, "note": { "description": "The broker's note, e.g. why the client waived it.", "nullable": true, "type": "string", "maxLength": 2000 } }, "required": [ "outcome" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "life_insurance", "description": "The type of this record. Always `life_insurance`.", "type": "string", "enum": [ "life_insurance" ] }, "id": { "type": "string", "description": "Stable identifier for the deal's creditor life insurance record." }, "deal_id": { "type": "string", "description": "The deal the insurance is for. A deal has at most one." }, "quote_only": { "type": "boolean", "description": "True when the broker asked the insurer for a quote rather than applying." }, "status": { "type": "string", "enum": [ "draft", "quoted", "submitted", "pending", "approved", "declined", "cancelled", "error" ], "description": "Where the application is with the insurer: `draft` until the broker sends it, then `quoted`, `submitted`, `pending`, `approved`, `declined`, `cancelled`, or `error`." }, "status_detail": { "nullable": true, "description": "The insurer's own words on the status, when it gave any.", "type": "string" }, "monthly_premium": { "nullable": true, "description": "The client's monthly premium the insurer quoted, in dollars. Null until there is a quote.", "type": "number" }, "commission_amount": { "nullable": true, "description": "What the broker earns on the policy, in dollars, as the broker entered it. Null until entered.", "type": "number" }, "commission_status": { "nullable": true, "description": "Where that commission is: `pending`, `confirmed`, `paid`, or `clawed_back`. Null until entered.", "type": "string", "enum": [ "pending", "confirmed", "paid", "clawed_back" ] }, "commission_paid_at": { "nullable": true, "description": "When the commission was collected. Null until it is.", "type": "string" }, "outcome": { "type": "string", "enum": [ "not_offered", "offered", "accepted", "waived", "referral", "not_supported" ], "description": "Where the conversation with the client landed: `not_offered` until the broker offers it, then `offered`, `accepted`, `waived`, `referral`, or `not_supported`." }, "outcome_at": { "nullable": true, "description": "When the outcome was recorded.", "type": "string" }, "outcome_by_user_id": { "nullable": true, "description": "The broker who recorded the outcome.", "type": "string" }, "outcome_note": { "nullable": true, "description": "The broker's note on the outcome, e.g. why the client waived it.", "type": "string" }, "consent_id": { "nullable": true, "description": "The client's consent that let BrokerPlus send their file to the insurer. Null until it was sent.", "type": "string" }, "certificate_number": { "nullable": true, "description": "The insurer's certificate number, which shows the client is covered. Null until it arrives.", "type": "string" }, "certificate_received_at": { "nullable": true, "description": "When the certificate arrived.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the broker sent the application or quote request.", "type": "string" }, "last_status_at": { "nullable": true, "description": "When the insurer last changed the status.", "type": "string" }, "created_at": { "type": "string", "description": "When the record was created." }, "updated_at": { "type": "string", "description": "When the record last changed." } }, "required": [ "object", "id", "deal_id", "quote_only", "status", "status_detail", "monthly_premium", "commission_amount", "commission_status", "commission_paid_at", "outcome", "outcome_at", "outcome_by_user_id", "outcome_note", "consent_id", "certificate_number", "certificate_received_at", "submitted_at", "last_status_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants": { "get": { "operationId": "listDealApplicants", "summary": "List a deal's applicants", "description": "Everyone on the application: the primary applicant, co-applicants and guarantors, each with their employment history and any income that does not come from a job. Read a person's name and contact details from the `contact_id`. Social insurance numbers are never returned.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant", "description": "The type of this record. Always `applicant`.", "type": "string", "enum": [ "applicant" ] }, "id": { "type": "string", "description": "Stable identifier for the applicant." }, "deal_id": { "type": "string", "description": "Deal this applicant belongs to." }, "contact_id": { "type": "string", "description": "Contact record for this person. Use it to read their name and contact details." }, "role": { "type": "string", "description": "`primary`, `co_applicant`, or `guarantor`." }, "middle_name": { "nullable": true, "description": "Middle name.", "type": "string" }, "marital_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Marital status, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Marital status, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Marital status." }, "number_of_dependents": { "nullable": true, "description": "Number of dependents.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resident_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Residency status in Canada, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Residency status in Canada, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Residency status." }, "relationship_to_primary": { "type": "object", "properties": { "code": { "nullable": true, "description": "Relationship to the primary applicant, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Relationship to the primary applicant, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Relationship to the primary applicant." }, "honorific": { "type": "object", "properties": { "code": { "nullable": true, "description": "Title, e.g. Mr. or Dr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Title, e.g. Mr. or Dr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Honorific." }, "suffix": { "type": "object", "properties": { "code": { "nullable": true, "description": "Name suffix, e.g. Jr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Name suffix, e.g. Jr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Name suffix." }, "sex": { "type": "object", "properties": { "code": { "nullable": true, "description": "Sex, as the lender application records it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Sex, as the lender application records it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Sex." }, "correspondence_language": { "type": "object", "properties": { "code": { "nullable": true, "description": "The language the lender writes to the applicant in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The language the lender writes to the applicant in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Correspondence language." }, "employments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false }, "description": "Employment history, most recent first." }, "income_sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false }, "description": "Income that does not come from employment." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false }, "description": "Where the applicant lives and has lived, and any mailing address, most recent first." }, "phones": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false }, "description": "The applicant's phone numbers, the preferred one first." }, "included_in_submission": { "type": "boolean", "description": "`true` when the primary mortgage application includes this applicant." }, "created_at": { "type": "string", "description": "When the applicant was added, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the applicant last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "contact_id", "role", "middle_name", "marital_status", "number_of_dependents", "resident_type", "relationship_to_primary", "honorific", "suffix", "sex", "correspondence_language", "employments", "income_sources", "addresses", "phones", "included_in_submission", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealApplicant", "summary": "Add an applicant to the application", "description": "Gives a borrower on the deal their application detail. The contact must already be on the deal as a borrower: add them first with `POST /deals/{id}/participants`. If the deal has no application yet, this creates one.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The contact to add to the application. The contact must already be on the deal as a borrower. Put them on the deal first with `POST /deals/{id}/participants`." }, "role": { "description": "`primary`, `co_applicant`, or `guarantor`. On create, the default comes from the participant role.", "type": "string", "enum": [ "primary", "co_applicant", "guarantor" ] }, "middle_name": { "description": "Middle name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "honorific": { "description": "Honorific, as the numeric `code` that `honorific` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "suffix": { "description": "Name suffix, as the numeric `code` that `suffix` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "sex": { "description": "Sex, as the numeric `code` that `sex` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "correspondence_language": { "description": "Correspondence language, as the numeric `code` that `correspondence_language` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "marital_status": { "description": "Marital status, as the numeric `code` that `marital_status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "number_of_dependents": { "description": "Number of dependents. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 50 }, "resident_type": { "description": "Residency status, as the numeric `code` that `resident_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 99 ] }, "relationship_to_primary": { "description": "Relationship to the primary applicant, as the numeric `code` that `relationship_to_primary` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 3, 4, 6, 8, 10, 12, 14, 99 ] } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant", "description": "The type of this record. Always `applicant`.", "type": "string", "enum": [ "applicant" ] }, "id": { "type": "string", "description": "Stable identifier for the applicant." }, "deal_id": { "type": "string", "description": "Deal this applicant belongs to." }, "contact_id": { "type": "string", "description": "Contact record for this person. Use it to read their name and contact details." }, "role": { "type": "string", "description": "`primary`, `co_applicant`, or `guarantor`." }, "middle_name": { "nullable": true, "description": "Middle name.", "type": "string" }, "marital_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Marital status, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Marital status, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Marital status." }, "number_of_dependents": { "nullable": true, "description": "Number of dependents.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resident_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Residency status in Canada, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Residency status in Canada, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Residency status." }, "relationship_to_primary": { "type": "object", "properties": { "code": { "nullable": true, "description": "Relationship to the primary applicant, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Relationship to the primary applicant, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Relationship to the primary applicant." }, "honorific": { "type": "object", "properties": { "code": { "nullable": true, "description": "Title, e.g. Mr. or Dr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Title, e.g. Mr. or Dr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Honorific." }, "suffix": { "type": "object", "properties": { "code": { "nullable": true, "description": "Name suffix, e.g. Jr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Name suffix, e.g. Jr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Name suffix." }, "sex": { "type": "object", "properties": { "code": { "nullable": true, "description": "Sex, as the lender application records it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Sex, as the lender application records it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Sex." }, "correspondence_language": { "type": "object", "properties": { "code": { "nullable": true, "description": "The language the lender writes to the applicant in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The language the lender writes to the applicant in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Correspondence language." }, "employments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false }, "description": "Employment history, most recent first." }, "income_sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false }, "description": "Income that does not come from employment." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false }, "description": "Where the applicant lives and has lived, and any mailing address, most recent first." }, "phones": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false }, "description": "The applicant's phone numbers, the preferred one first." }, "included_in_submission": { "type": "boolean", "description": "`true` when the primary mortgage application includes this applicant." }, "created_at": { "type": "string", "description": "When the applicant was added, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the applicant last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "contact_id", "role", "middle_name", "marital_status", "number_of_dependents", "resident_type", "relationship_to_primary", "honorific", "suffix", "sex", "correspondence_language", "employments", "income_sources", "addresses", "phones", "included_in_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The contact is not on the deal as a borrower (NOT_A_BORROWER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The contact is already an applicant on the deal (APPLICANT_EXISTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/financials": { "get": { "operationId": "getDealFinancials", "summary": "Retrieve a deal's financial position", "description": "What the applicants own, what they owe, and where the down payment comes from. A liability with `from_credit_bureau` set to `true` came from a credit report, which carries its own redistribution obligations. Account numbers are never returned.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "Deal these financials belong to." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "asset", "description": "The type of this record. Always `asset`.", "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "description": "Stable identifier for the asset." }, "deal_id": { "type": "string", "description": "Deal this asset belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the asset, when one person owns it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the asset is a property." }, "asset_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of asset, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of asset, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Asset type. `null` for real estate." }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "value": { "type": "number", "description": "Value of the asset, in dollars." }, "available_as_collateral": { "type": "boolean", "description": "`true` when the asset can secure the loan." }, "address": { "nullable": true, "description": "Street address. Real estate only.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite. Real estate only.", "type": "string" }, "city": { "nullable": true, "description": "City or town. Real estate only.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`. Real estate only.", "type": "string" }, "mortgage_balance": { "nullable": true, "description": "Balance owing on this property, in dollars. Real estate only.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on this property's mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly payment on this property, in dollars.", "type": "number" }, "applied_to_down_payment": { "nullable": true, "description": "How much of this asset goes into the down payment, in dollars. `null` when nobody stated it.", "type": "number" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "asset_type", "description", "value", "available_as_collateral", "address", "unit", "city", "province", "mortgage_balance", "interest_rate", "monthly_payment", "applied_to_down_payment", "owner_contact_ids" ], "additionalProperties": false }, "description": "What the applicants own." }, "liabilities": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "liability", "description": "The type of this record. Always `liability`.", "type": "string", "enum": [ "liability" ] }, "id": { "type": "string", "description": "Stable identifier for the liability." }, "deal_id": { "type": "string", "description": "Deal this liability belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owes the debt, when one person owes it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the debt is secured by a property." }, "liability_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of debt, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of debt, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Liability type. `null` for real estate." }, "lender_name": { "nullable": true, "description": "Who the debt is owed to.", "type": "string" }, "from_credit_bureau": { "type": "boolean", "description": "`true` when the row came from a credit report rather than from the applicant. Consumer report data carries its own redistribution obligations. Check yours before you store or forward it." }, "pay_off": { "type": "boolean", "description": "`true` when the broker plans to pay the debt out at closing." }, "outstanding_balance": { "nullable": true, "description": "Balance owing, in dollars.", "type": "number" }, "monthly_repayment": { "nullable": true, "description": "Required monthly payment, in dollars.", "type": "number" }, "credit_limit": { "nullable": true, "description": "Credit limit, in dollars. Revolving debt only.", "type": "number" }, "net_rate": { "nullable": true, "description": "Rate on the debt as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "maturity_date": { "nullable": true, "description": "When the debt matures, as `YYYY-MM-DD`.", "type": "string" }, "debt_type": { "nullable": true, "description": "How BrokerPlus groups the debt for consolidation: `credit_card`, `auto_loan`, `personal_loc`, `student_loan`, `cra_tax`, `second_mortgage`, `heloc`, `other_secured`, or `other`. `null` when it was not grouped.", "type": "string" }, "secured_by_home": { "nullable": true, "description": "`true` when the broker marked this line of credit as secured against a home. The debt service ratios then count it at the higher of its stated payment and its balance repaid over 25 years at the qualifying rate. `null` when nobody has said.", "type": "boolean" }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "original_loan_amount": { "nullable": true, "description": "The amount first borrowed, in dollars. Secured debt only.", "type": "number" }, "closing_date": { "nullable": true, "description": "When the debt was taken out. Secured debt only.", "type": "string" }, "charge_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The charge position on title, e.g. second, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The charge position on title, e.g. second, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Charge type." }, "repayment_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is repaid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is repaid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Repayment type." }, "redemption_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Whether the debt is paid out, and how, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Whether the debt is paid out, and how, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Redemption status." }, "rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type." }, "payoff_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan." }, "source_deal_id": { "nullable": true, "description": "Another deal whose mortgage balance this row follows. Changes to that balance reach this row.", "type": "string" }, "property_id": { "nullable": true, "description": "The property this debt is the mortgage on. Resolve against `GET /deals/{id}/other-properties`.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "liability_type", "lender_name", "from_credit_bureau", "pay_off", "outstanding_balance", "monthly_repayment", "credit_limit", "net_rate", "maturity_date", "debt_type", "secured_by_home", "description", "original_loan_amount", "closing_date", "charge_type", "repayment_type", "redemption_status", "rate_type", "payoff_type", "source_deal_id", "property_id", "owner_contact_ids" ], "additionalProperties": false }, "description": "What the applicants owe." }, "downpayments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "downpayment", "description": "The type of this record. Always `downpayment`.", "type": "string", "enum": [ "downpayment" ] }, "id": { "type": "string", "description": "Stable identifier for the down payment." }, "source_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Where the money comes from, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Where the money comes from, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Down payment source." }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "amount": { "type": "number", "description": "Amount from this source, in dollars." } }, "required": [ "object", "id", "source_type", "description", "amount" ], "additionalProperties": false }, "description": "Where the down payment comes from." } }, "required": [ "deal_id", "assets", "liabilities", "downpayments" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/application/terms-history": { "get": { "operationId": "listDealTermsHistory", "summary": "List changes to a deal's loan terms", "description": "One row for each change to one of nine loan terms on the deal's application, oldest first. Each row gives the old and new value, when the change was made, and who made it. A change made through an API key names the broker who owns the key.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "terms_change", "description": "The type of this record. Always `terms_change`.", "type": "string", "enum": [ "terms_change" ] }, "id": { "type": "string", "description": "Stable identifier for the change." }, "field": { "type": "string", "description": "The application field that changed: `loan_amount`, `net_rate`, `term_months`, `amortization_months`, `rate_type`, `purchase_price`, `payment_amount`, `payment_frequency`, or `mortgage_insurer`." }, "old_value": { "nullable": true, "description": "The value before the change, as text. A coded field holds its numeric code. `null` when it was not set.", "type": "string" }, "new_value": { "nullable": true, "description": "The value after the change, as text. `null` when the change cleared it.", "type": "string" }, "source": { "type": "string", "enum": [ "user", "vendor_sync", "deal_import", "unattributed" ], "description": "What made the change: `user` (a broker, in BrokerPlus or through an API key), `vendor_sync` (an origination system), `deal_import` (an import), or `unattributed`." }, "changed_by_user_id": { "nullable": true, "description": "The broker who made the change. `null` when no person is recorded.", "type": "string" }, "changed_by_name": { "nullable": true, "description": "That broker's name, for display.", "type": "string" }, "changed_at": { "type": "string", "description": "When the change was made, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "field", "old_value", "new_value", "source", "changed_by_user_id", "changed_by_name", "changed_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` is not an ISO 8601 timestamp (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}": { "get": { "operationId": "getDealApplicant", "summary": "Retrieve one applicant", "description": "One applicant on the deal's application, with their employment, their other income, their addresses and their phone numbers. Social insurance numbers are never returned.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant", "description": "The type of this record. Always `applicant`.", "type": "string", "enum": [ "applicant" ] }, "id": { "type": "string", "description": "Stable identifier for the applicant." }, "deal_id": { "type": "string", "description": "Deal this applicant belongs to." }, "contact_id": { "type": "string", "description": "Contact record for this person. Use it to read their name and contact details." }, "role": { "type": "string", "description": "`primary`, `co_applicant`, or `guarantor`." }, "middle_name": { "nullable": true, "description": "Middle name.", "type": "string" }, "marital_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Marital status, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Marital status, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Marital status." }, "number_of_dependents": { "nullable": true, "description": "Number of dependents.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resident_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Residency status in Canada, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Residency status in Canada, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Residency status." }, "relationship_to_primary": { "type": "object", "properties": { "code": { "nullable": true, "description": "Relationship to the primary applicant, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Relationship to the primary applicant, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Relationship to the primary applicant." }, "honorific": { "type": "object", "properties": { "code": { "nullable": true, "description": "Title, e.g. Mr. or Dr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Title, e.g. Mr. or Dr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Honorific." }, "suffix": { "type": "object", "properties": { "code": { "nullable": true, "description": "Name suffix, e.g. Jr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Name suffix, e.g. Jr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Name suffix." }, "sex": { "type": "object", "properties": { "code": { "nullable": true, "description": "Sex, as the lender application records it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Sex, as the lender application records it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Sex." }, "correspondence_language": { "type": "object", "properties": { "code": { "nullable": true, "description": "The language the lender writes to the applicant in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The language the lender writes to the applicant in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Correspondence language." }, "employments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false }, "description": "Employment history, most recent first." }, "income_sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false }, "description": "Income that does not come from employment." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false }, "description": "Where the applicant lives and has lived, and any mailing address, most recent first." }, "phones": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false }, "description": "The applicant's phone numbers, the preferred one first." }, "included_in_submission": { "type": "boolean", "description": "`true` when the primary mortgage application includes this applicant." }, "created_at": { "type": "string", "description": "When the applicant was added, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the applicant last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "contact_id", "role", "middle_name", "marital_status", "number_of_dependents", "resident_type", "relationship_to_primary", "honorific", "suffix", "sex", "correspondence_language", "employments", "income_sources", "addresses", "phones", "included_in_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealApplicant", "summary": "Update an applicant", "description": "Changes the applicant's role, marital status, dependents, residency, or relationship to the primary applicant. Send only the fields to change. Coded fields take the numeric `code` that the read returns.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "`primary`, `co_applicant`, or `guarantor`. On create, the default comes from the participant role.", "type": "string", "enum": [ "primary", "co_applicant", "guarantor" ] }, "middle_name": { "description": "Middle name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "honorific": { "description": "Honorific, as the numeric `code` that `honorific` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "suffix": { "description": "Name suffix, as the numeric `code` that `suffix` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "sex": { "description": "Sex, as the numeric `code` that `sex` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "correspondence_language": { "description": "Correspondence language, as the numeric `code` that `correspondence_language` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "marital_status": { "description": "Marital status, as the numeric `code` that `marital_status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "number_of_dependents": { "description": "Number of dependents. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 50 }, "resident_type": { "description": "Residency status, as the numeric `code` that `resident_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 99 ] }, "relationship_to_primary": { "description": "Relationship to the primary applicant, as the numeric `code` that `relationship_to_primary` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 3, 4, 6, 8, 10, 12, 14, 99 ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant", "description": "The type of this record. Always `applicant`.", "type": "string", "enum": [ "applicant" ] }, "id": { "type": "string", "description": "Stable identifier for the applicant." }, "deal_id": { "type": "string", "description": "Deal this applicant belongs to." }, "contact_id": { "type": "string", "description": "Contact record for this person. Use it to read their name and contact details." }, "role": { "type": "string", "description": "`primary`, `co_applicant`, or `guarantor`." }, "middle_name": { "nullable": true, "description": "Middle name.", "type": "string" }, "marital_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Marital status, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Marital status, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Marital status." }, "number_of_dependents": { "nullable": true, "description": "Number of dependents.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resident_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Residency status in Canada, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Residency status in Canada, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Residency status." }, "relationship_to_primary": { "type": "object", "properties": { "code": { "nullable": true, "description": "Relationship to the primary applicant, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Relationship to the primary applicant, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Relationship to the primary applicant." }, "honorific": { "type": "object", "properties": { "code": { "nullable": true, "description": "Title, e.g. Mr. or Dr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Title, e.g. Mr. or Dr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Honorific." }, "suffix": { "type": "object", "properties": { "code": { "nullable": true, "description": "Name suffix, e.g. Jr., as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Name suffix, e.g. Jr., in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Name suffix." }, "sex": { "type": "object", "properties": { "code": { "nullable": true, "description": "Sex, as the lender application records it, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Sex, as the lender application records it, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Sex." }, "correspondence_language": { "type": "object", "properties": { "code": { "nullable": true, "description": "The language the lender writes to the applicant in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The language the lender writes to the applicant in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Correspondence language." }, "employments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false }, "description": "Employment history, most recent first." }, "income_sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false }, "description": "Income that does not come from employment." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false }, "description": "Where the applicant lives and has lived, and any mailing address, most recent first." }, "phones": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false }, "description": "The applicant's phone numbers, the preferred one first." }, "included_in_submission": { "type": "boolean", "description": "`true` when the primary mortgage application includes this applicant." }, "created_at": { "type": "string", "description": "When the applicant was added, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the applicant last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "contact_id", "role", "middle_name", "marital_status", "number_of_dependents", "resident_type", "relationship_to_primary", "honorific", "suffix", "sex", "correspondence_language", "employments", "income_sources", "addresses", "phones", "included_in_submission", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealApplicant", "summary": "Remove an applicant from the application", "description": "Deletes the applicant's application detail: their employment, their income, and their share of any asset or debt. The contact stays on the deal. To take them off the deal too, use `DELETE /deals/{id}/participants/{contactId}` after this.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The applicant is the primary applicant (PRIMARY_APPLICANT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/employments": { "post": { "operationId": "createApplicantEmployment", "summary": "Add a job to an applicant", "description": "Adds one employment record, with its income lines. The gross debt service and total debt service ratios on the application include the new income on the next read.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employer_name": { "description": "Name of the employer. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "job_title": { "description": "Job title. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "current": { "description": "`true` when this is a current job. The default on create is `true`.", "type": "boolean" }, "status": { "description": "Employment status, as the numeric `code` that `status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 70, 80, 99 ] }, "type": { "description": "Employment type, as the numeric `code` that `type` returns on read. Send null to clear. The temporary codes 3, 4 and 6 are no longer used: 3 is saved as 1, 4 as 2, and 6 as 5.", "nullable": true, "type": "number", "enum": [ 1, 2, 5, 7 ] }, "industry": { "description": "Industry, as the numeric `code` that `industry` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 99 ] }, "occupation": { "description": "Occupation, as the numeric `code` that `occupation` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "city": { "description": "Employer city or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "province": { "description": "Employer province, as the numeric `code` that `province` returns on read, or as the two-letter code, e.g. `ON`. Send null to clear.", "nullable": true, "anyOf": [ { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] } ] }, "started_on": { "description": "Date the applicant started this job. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "ended_on": { "description": "Date the applicant left this job. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "started_in_industry_on": { "description": "Date the applicant started in this industry. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "industry_varies": { "description": "`true` when the applicant works across industries. Leave `industry` empty then.", "type": "boolean" }, "business_type": { "description": "Business type, as the numeric `code` that `business_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3 ] }, "employer_unit_number": { "description": "Employer unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_street_number": { "description": "Employer street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_street_name": { "description": "Employer street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "employer_street_type": { "description": "Employer street type, as the numeric `code` that `employer_street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "employer_street_direction": { "description": "Employer street direction, as the numeric `code` that `employer_street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "employer_postal_code": { "description": "Employer postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "employer_phone_area_code": { "description": "Employer phone area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "employer_phone_number": { "description": "Employer phone number, without the area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_phone_extension": { "description": "Employer phone extension. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "incomes": { "description": "The complete list of income lines for this job. A line with an `id` changes that line, a line without one is added, and a line you leave out is removed. Leave the field out to keep the lines as they are.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The `id` of an income line to keep and change. Leave it out to add a line.", "type": "string" }, "income_type": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 99 ], "description": "Kind of earned income, as the numeric `code` that `income_type` returns on read." }, "payment_frequency": { "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ], "description": "How often it is paid, as the numeric `code` that `payment_frequency` returns on read." }, "amount": { "type": "number", "minimum": 0, "description": "Amount paid each period, in dollars. Not annualized." } }, "required": [ "income_type", "payment_frequency", "amount" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/employments/{employmentId}": { "patch": { "operationId": "updateApplicantEmployment", "summary": "Update a job", "description": "Changes one employment record. Send only the fields to change. When you send `incomes`, it is the complete list for this job: lines you leave out are removed. A status with no employer, such as retired, clears the employer fields.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "employmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employer_name": { "description": "Name of the employer. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "job_title": { "description": "Job title. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "current": { "description": "`true` when this is a current job. The default on create is `true`.", "type": "boolean" }, "status": { "description": "Employment status, as the numeric `code` that `status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 70, 80, 99 ] }, "type": { "description": "Employment type, as the numeric `code` that `type` returns on read. Send null to clear. The temporary codes 3, 4 and 6 are no longer used: 3 is saved as 1, 4 as 2, and 6 as 5.", "nullable": true, "type": "number", "enum": [ 1, 2, 5, 7 ] }, "industry": { "description": "Industry, as the numeric `code` that `industry` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 99 ] }, "occupation": { "description": "Occupation, as the numeric `code` that `occupation` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 99 ] }, "city": { "description": "Employer city or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "province": { "description": "Employer province, as the numeric `code` that `province` returns on read, or as the two-letter code, e.g. `ON`. Send null to clear.", "nullable": true, "anyOf": [ { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] } ] }, "started_on": { "description": "Date the applicant started this job. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "ended_on": { "description": "Date the applicant left this job. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "started_in_industry_on": { "description": "Date the applicant started in this industry. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "industry_varies": { "description": "`true` when the applicant works across industries. Leave `industry` empty then.", "type": "boolean" }, "business_type": { "description": "Business type, as the numeric `code` that `business_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3 ] }, "employer_unit_number": { "description": "Employer unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_street_number": { "description": "Employer street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_street_name": { "description": "Employer street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "employer_street_type": { "description": "Employer street type, as the numeric `code` that `employer_street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "employer_street_direction": { "description": "Employer street direction, as the numeric `code` that `employer_street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "employer_postal_code": { "description": "Employer postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "employer_phone_area_code": { "description": "Employer phone area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "employer_phone_number": { "description": "Employer phone number, without the area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "employer_phone_extension": { "description": "Employer phone extension. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "incomes": { "description": "The complete list of income lines for this job. A line with an `id` changes that line, a line without one is added, and a line you leave out is removed. Leave the field out to keep the lines as they are.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The `id` of an income line to keep and change. Leave it out to add a line.", "type": "string" }, "income_type": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 99 ], "description": "Kind of earned income, as the numeric `code` that `income_type` returns on read." }, "payment_frequency": { "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ], "description": "How often it is paid, as the numeric `code` that `payment_frequency` returns on read." }, "amount": { "type": "number", "minimum": 0, "description": "Amount paid each period, in dollars. Not annualized." } }, "required": [ "income_type", "payment_frequency", "amount" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "employment", "description": "The type of this record. Always `employment`.", "type": "string", "enum": [ "employment" ] }, "id": { "type": "string", "description": "Stable identifier for the employment record." }, "employer_name": { "nullable": true, "description": "Name of the employer.", "type": "string" }, "job_title": { "nullable": true, "description": "Job title.", "type": "string" }, "current": { "type": "boolean", "description": "`true` when this is the applicant's current employment." }, "status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment status, e.g. full time, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment status, e.g. full time, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment status." }, "type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Employment type, e.g. salaried, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Employment type, e.g. salaried, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employment type." }, "industry": { "type": "object", "properties": { "code": { "nullable": true, "description": "Industry the employer operates in, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Industry the employer operates in, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Industry." }, "occupation": { "type": "object", "properties": { "code": { "nullable": true, "description": "Occupation category, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Occupation category, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Occupation." }, "city": { "nullable": true, "description": "Employer city or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Employer province." }, "started_on": { "nullable": true, "description": "Date the applicant started this job, as `YYYY-MM-DD`.", "type": "string" }, "ended_on": { "nullable": true, "description": "Date the applicant left this job. `null` while the job continues.", "type": "string" }, "started_in_industry_on": { "nullable": true, "description": "Date the applicant started in this industry.", "type": "string" }, "industry_varies": { "type": "boolean", "description": "`true` when the applicant works across industries, so `industry` names none of them." }, "business_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a self-employed applicant's business is set up, e.g. sole proprietor, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Business type. Self-employed applicants only." }, "employer_unit_number": { "nullable": true, "description": "Employer unit or suite.", "type": "string" }, "employer_street_number": { "nullable": true, "description": "Employer street number.", "type": "string" }, "employer_street_name": { "nullable": true, "description": "Employer street name, without the type or direction.", "type": "string" }, "employer_street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street type." }, "employer_street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Employer street direction." }, "employer_postal_code": { "nullable": true, "description": "Employer postal code.", "type": "string" }, "employer_phone_area_code": { "nullable": true, "description": "Employer phone area code, e.g. `416`.", "type": "string" }, "employer_phone_number": { "nullable": true, "description": "Employer phone number, without the area code.", "type": "string" }, "employer_phone_extension": { "nullable": true, "description": "Employer phone extension.", "type": "string" }, "incomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the income line." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of earned income, e.g. salary or bonus, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is paid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is paid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount paid each period, in dollars. Not annualized." }, "amount_basis": { "nullable": true, "description": "`per_period` when the amount was stated as what each payment is. `null` on older lines, where BrokerPlus reads a large monthly or bi-weekly figure as annual.", "type": "string" } }, "required": [ "id", "income_type", "payment_frequency", "amount", "amount_basis" ], "additionalProperties": false }, "description": "What this job pays. One line for each kind of pay." } }, "required": [ "object", "id", "employer_name", "job_title", "current", "status", "type", "industry", "occupation", "city", "province", "started_on", "ended_on", "started_in_industry_on", "industry_varies", "business_type", "employer_unit_number", "employer_street_number", "employer_street_name", "employer_street_type", "employer_street_direction", "employer_postal_code", "employer_phone_area_code", "employer_phone_number", "employer_phone_extension", "incomes" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteApplicantEmployment", "summary": "Remove a job", "description": "Deletes one employment record and its income lines.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "employmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/income-sources": { "post": { "operationId": "createApplicantIncomeSource", "summary": "Add other income to an applicant", "description": "Adds one income line that does not come from a job, for example a pension or child support.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "income_type": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 99 ], "description": "Kind of income, as the numeric `code` that `income_type` returns on read." }, "payment_frequency": { "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ], "description": "How often it is received, as the numeric `code` that `payment_frequency` returns on read." }, "amount": { "type": "number", "minimum": 0, "description": "Amount received each period, in dollars. Not annualized." }, "details": { "description": "Free-text detail. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 } }, "required": [ "income_type", "payment_frequency", "amount" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/income-sources/{incomeSourceId}": { "patch": { "operationId": "updateApplicantIncomeSource", "summary": "Update other income", "description": "Changes one income line. Send only the fields to change.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "incomeSourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "income_type": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 99 ], "description": "Kind of income, as the numeric `code` that `income_type` returns on read." }, "payment_frequency": { "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ], "description": "How often it is received, as the numeric `code` that `payment_frequency` returns on read." }, "amount": { "type": "number", "minimum": 0, "description": "Amount received each period, in dollars. Not annualized." }, "details": { "description": "Free-text detail. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "income_source", "description": "The type of this record. Always `income_source`.", "type": "string", "enum": [ "income_source" ] }, "id": { "type": "string", "description": "Stable identifier for the income source." }, "income_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of income, e.g. pension, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of income, e.g. pension, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Income type." }, "payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the income is received, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the income is received, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency." }, "amount": { "type": "number", "description": "Amount received each period, in dollars. Not annualized." }, "details": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" } }, "required": [ "object", "id", "income_type", "payment_frequency", "amount", "details" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteApplicantIncomeSource", "summary": "Remove other income", "description": "Deletes one income line.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "incomeSourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/addresses": { "post": { "operationId": "createApplicantAddress", "summary": "Add an address to an applicant", "description": "Adds one address: where the applicant lives now (`current`), a home they lived in before (`previous`), or a mailing address (`correspondence`). Lenders ask for about three years of address history, so add each earlier home as its own `previous` address with its dates.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "`current`, `previous` or `correspondence`. The default on create is `current`. Add each earlier home as its own `previous` address.", "type": "string", "enum": [ "current", "previous", "correspondence" ] }, "occupancy_type": { "description": "How the applicant lives there. One of the `occupancy_type` values on read. Send null to clear.", "nullable": true, "type": "string", "enum": [ "owner_occupied", "partial_owner_occupied", "rental", "tenant", "none" ] }, "unit_number": { "description": "Unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_number": { "description": "Street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_name": { "description": "Street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "street_type": { "description": "Street type, as the numeric `code` that `street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "street_direction": { "description": "Street direction, as the numeric `code` that `street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "city": { "description": "City or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "province": { "description": "Province, as the numeric `code` that `province` returns on read, or as the two-letter code, e.g. `ON`. Send null to clear.", "nullable": true, "anyOf": [ { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] } ] }, "postal_code": { "description": "Postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "country": { "description": "Country, as the numeric `code` that `country` returns on read. The default on create is Canada.", "type": "number", "enum": [ 1, 2, 99 ] }, "started_on": { "description": "When the applicant started living at this address. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "ended_on": { "description": "When the applicant stopped living at this address. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "current_property_intended_action": { "description": "What happens to this home after the new mortgage, as the numeric `code` that `current_property_intended_action` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3 ] }, "annual_heating_amount": { "description": "Yearly heating cost of this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "annual_tax_amount": { "description": "Yearly property tax on this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "annual_gross_rental_income": { "description": "Yearly rent the applicant collects on this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "rental_offset_pct": { "description": "The share of rent that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "rental_calc_type": { "description": "Rental calculation method, as the numeric `code` that `rental_calc_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "monthly_rent_paid": { "description": "Rent the applicant pays each month, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "tenancy_type": { "description": "Tenancy type, as the numeric `code` that `tenancy_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40 ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/addresses/{addressId}": { "patch": { "operationId": "updateApplicantAddress", "summary": "Update an address", "description": "Changes one address. Send only the fields to change. Coded fields take the numeric `code` that the read returns.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "`current`, `previous` or `correspondence`. The default on create is `current`. Add each earlier home as its own `previous` address.", "type": "string", "enum": [ "current", "previous", "correspondence" ] }, "occupancy_type": { "description": "How the applicant lives there. One of the `occupancy_type` values on read. Send null to clear.", "nullable": true, "type": "string", "enum": [ "owner_occupied", "partial_owner_occupied", "rental", "tenant", "none" ] }, "unit_number": { "description": "Unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_number": { "description": "Street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "street_name": { "description": "Street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "street_type": { "description": "Street type, as the numeric `code` that `street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "street_direction": { "description": "Street direction, as the numeric `code` that `street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "city": { "description": "City or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 100 }, "province": { "description": "Province, as the numeric `code` that `province` returns on read, or as the two-letter code, e.g. `ON`. Send null to clear.", "nullable": true, "anyOf": [ { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] } ] }, "postal_code": { "description": "Postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 }, "country": { "description": "Country, as the numeric `code` that `country` returns on read. The default on create is Canada.", "type": "number", "enum": [ 1, 2, 99 ] }, "started_on": { "description": "When the applicant started living at this address. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "ended_on": { "description": "When the applicant stopped living at this address. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "current_property_intended_action": { "description": "What happens to this home after the new mortgage, as the numeric `code` that `current_property_intended_action` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3 ] }, "annual_heating_amount": { "description": "Yearly heating cost of this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "annual_tax_amount": { "description": "Yearly property tax on this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "annual_gross_rental_income": { "description": "Yearly rent the applicant collects on this home, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "rental_offset_pct": { "description": "The share of rent that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "rental_calc_type": { "description": "Rental calculation method, as the numeric `code` that `rental_calc_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "monthly_rent_paid": { "description": "Rent the applicant pays each month, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "tenancy_type": { "description": "Tenancy type, as the numeric `code` that `tenancy_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40 ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant_address", "description": "The type of this record. Always `applicant_address`.", "type": "string", "enum": [ "applicant_address" ] }, "id": { "type": "string", "description": "Stable identifier for the address." }, "type": { "type": "string", "description": "`current` where the applicant lives now, `previous` where they lived before, or `correspondence` for a mailing address that is not where they live." }, "occupancy_type": { "nullable": true, "description": "How the applicant lives there: `owner_occupied`, `partial_owner_occupied`, `rental`, `tenant` or `none`. Null if not recorded.", "type": "string" }, "unit_number": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name, without the type or direction.", "type": "string" }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "type": "object", "properties": { "code": { "nullable": true, "description": "Canadian province or territory, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Canadian province or territory, in words. `Unknown` if the code is one we cannot name.", "type": "string" }, "abbreviation": { "nullable": true, "description": "The two-letter code, e.g. `ON`. Null when no province is set or the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label", "abbreviation" ], "additionalProperties": false, "description": "Province." }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "country": { "type": "object", "properties": { "code": { "nullable": true, "description": "Country, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Country, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Country. Canada unless the broker said otherwise." }, "started_on": { "nullable": true, "description": "When the applicant started living at this address, as `YYYY-MM-DD`. Null if not recorded.", "type": "string" }, "ended_on": { "nullable": true, "description": "When the applicant stopped living at this address, as `YYYY-MM-DD`. Null for the current address.", "type": "string" }, "current_property_intended_action": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the applicant plans for the home they live in now, e.g. selling, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "What happens to this home after the new mortgage. Current address only." }, "annual_heating_amount": { "nullable": true, "description": "Yearly heating cost of this home, in dollars.", "type": "number" }, "annual_tax_amount": { "nullable": true, "description": "Yearly property tax on this home, in dollars.", "type": "number" }, "annual_gross_rental_income": { "nullable": true, "description": "Yearly rent the applicant collects on this home, in dollars. For a `rental` or partly rented home.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_rent_paid": { "nullable": true, "description": "Rent the applicant pays each month, in dollars. For a `tenant`. Null if not recorded.", "type": "number" }, "tenancy_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How a tenant lives there, e.g. leased, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How a tenant lives there, e.g. leased, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Tenancy type. Tenants only." } }, "required": [ "object", "id", "type", "occupancy_type", "unit_number", "street_number", "street_name", "street_type", "street_direction", "city", "province", "postal_code", "country", "started_on", "ended_on", "current_property_intended_action", "annual_heating_amount", "annual_tax_amount", "annual_gross_rental_income", "rental_offset_pct", "rental_calc_type", "monthly_rent_paid", "tenancy_type" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteApplicantAddress", "summary": "Remove an address", "description": "Deletes one address from the applicant.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/phones": { "post": { "operationId": "createApplicantPhone", "summary": "Add a phone number to an applicant", "description": "Adds one phone number to the applicant's application detail. This is the number the lender sees. It does not change the contact's own phone numbers.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "What the number is for, as the numeric `code` that `usage` returns on read." }, "preferred": { "description": "`true` when this is the number the applicant prefers. The default on create is `false`.", "type": "boolean" }, "country_code": { "description": "Country calling code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "area_code": { "description": "Area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "number": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Phone number, without the area code." }, "extension": { "description": "Extension. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 } }, "required": [ "usage", "number" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/applicants/{applicantId}/phones/{phoneId}": { "patch": { "operationId": "updateApplicantPhone", "summary": "Update a phone number", "description": "Changes one phone number. Send only the fields to change.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "What the number is for, as the numeric `code` that `usage` returns on read." }, "preferred": { "description": "`true` when this is the number the applicant prefers. The default on create is `false`.", "type": "boolean" }, "country_code": { "description": "Country calling code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "area_code": { "description": "Area code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 5 }, "number": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Phone number, without the area code." }, "extension": { "description": "Extension. Send null to clear.", "nullable": true, "type": "string", "maxLength": 10 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "applicant_phone", "description": "The type of this record. Always `applicant_phone`.", "type": "string", "enum": [ "applicant_phone" ] }, "id": { "type": "string", "description": "Stable identifier for the phone number." }, "usage": { "type": "object", "properties": { "code": { "nullable": true, "description": "What the number is for, e.g. mobile, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "What the number is for, e.g. mobile, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Phone type." }, "preferred": { "type": "boolean", "description": "`true` when this is the number the applicant prefers the lender to call." }, "country_code": { "nullable": true, "description": "Country calling code, e.g. `1`.", "type": "string" }, "area_code": { "nullable": true, "description": "Area code, e.g. `416`.", "type": "string" }, "number": { "type": "string", "description": "Phone number, without the area code." }, "extension": { "nullable": true, "description": "Extension.", "type": "string" } }, "required": [ "object", "id", "usage", "preferred", "country_code", "area_code", "number", "extension" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteApplicantPhone", "summary": "Remove a phone number", "description": "Deletes one phone number from the applicant.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "applicantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/assets": { "post": { "operationId": "createDealAsset", "summary": "Add an asset", "description": "Adds one asset that is not a property, for example savings or a vehicle. To add a property the applicants own, use `POST /deals/{id}/other-properties`.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "asset_type": { "description": "Kind of asset, as the numeric `code` that `asset_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 60, 70, 71, 72, 73, 99 ] }, "description": { "description": "Free-text detail, 50 characters maximum. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "value": { "type": "number", "minimum": 0, "description": "Value of the asset, in dollars." }, "available_as_collateral": { "description": "`true` when the asset can secure the loan.", "type": "boolean" }, "applied_to_down_payment": { "description": "How much of this asset goes into the down payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "asset", "description": "The type of this record. Always `asset`.", "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "description": "Stable identifier for the asset." }, "deal_id": { "type": "string", "description": "Deal this asset belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the asset, when one person owns it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the asset is a property." }, "asset_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of asset, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of asset, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Asset type. `null` for real estate." }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "value": { "type": "number", "description": "Value of the asset, in dollars." }, "available_as_collateral": { "type": "boolean", "description": "`true` when the asset can secure the loan." }, "address": { "nullable": true, "description": "Street address. Real estate only.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite. Real estate only.", "type": "string" }, "city": { "nullable": true, "description": "City or town. Real estate only.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`. Real estate only.", "type": "string" }, "mortgage_balance": { "nullable": true, "description": "Balance owing on this property, in dollars. Real estate only.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on this property's mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly payment on this property, in dollars.", "type": "number" }, "applied_to_down_payment": { "nullable": true, "description": "How much of this asset goes into the down payment, in dollars. `null` when nobody stated it.", "type": "number" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "asset_type", "description", "value", "available_as_collateral", "address", "unit", "city", "province", "mortgage_balance", "interest_rate", "monthly_payment", "applied_to_down_payment", "owner_contact_ids" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/assets/{assetId}": { "patch": { "operationId": "updateDealAsset", "summary": "Update an asset", "description": "Changes one asset. Send only the fields to change.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "asset_type": { "description": "Kind of asset, as the numeric `code` that `asset_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 60, 70, 71, 72, 73, 99 ] }, "description": { "description": "Free-text detail, 50 characters maximum. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "value": { "type": "number", "minimum": 0, "description": "Value of the asset, in dollars." }, "available_as_collateral": { "description": "`true` when the asset can secure the loan.", "type": "boolean" }, "applied_to_down_payment": { "description": "How much of this asset goes into the down payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "asset", "description": "The type of this record. Always `asset`.", "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "description": "Stable identifier for the asset." }, "deal_id": { "type": "string", "description": "Deal this asset belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the asset, when one person owns it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the asset is a property." }, "asset_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of asset, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of asset, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Asset type. `null` for real estate." }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "value": { "type": "number", "description": "Value of the asset, in dollars." }, "available_as_collateral": { "type": "boolean", "description": "`true` when the asset can secure the loan." }, "address": { "nullable": true, "description": "Street address. Real estate only.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite. Real estate only.", "type": "string" }, "city": { "nullable": true, "description": "City or town. Real estate only.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`. Real estate only.", "type": "string" }, "mortgage_balance": { "nullable": true, "description": "Balance owing on this property, in dollars. Real estate only.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on this property's mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly payment on this property, in dollars.", "type": "number" }, "applied_to_down_payment": { "nullable": true, "description": "How much of this asset goes into the down payment, in dollars. `null` when nobody stated it.", "type": "number" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "asset_type", "description", "value", "available_as_collateral", "address", "unit", "city", "province", "mortgage_balance", "interest_rate", "monthly_payment", "applied_to_down_payment", "owner_contact_ids" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealAsset", "summary": "Remove an asset", "description": "Deletes one asset.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/liabilities": { "post": { "operationId": "createDealLiability", "summary": "Add a debt", "description": "Adds one debt the applicants state. Debts from a credit report arrive only from a credit pull. The total debt service ratio includes the new debt on the next read.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "liability_type": { "description": "Kind of debt, as the numeric `code` that `liability_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 99 ] }, "lender_name": { "description": "Who the debt is owed to. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "pay_off": { "description": "`true` when the broker plans to pay the debt out at closing.", "type": "boolean" }, "outstanding_balance": { "description": "Balance owing, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_repayment": { "description": "Required monthly payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "credit_limit": { "description": "Credit limit, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "net_rate": { "description": "Rate on the debt as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "maturity_date": { "description": "When the debt matures. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "description": { "description": "Free-text detail. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "original_loan_amount": { "description": "The amount first borrowed, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "closing_date": { "description": "When the debt was taken out. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "charge_type": { "description": "Charge type, as the numeric `code` that `charge_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 99 ] }, "repayment_type": { "description": "Repayment type, as the numeric `code` that `repayment_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "redemption_status": { "description": "Redemption status, as the numeric `code` that `redemption_status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 7 ] }, "rate_type": { "description": "Rate type, as the numeric `code` that `rate_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 2, 12, 99 ] }, "payoff_type": { "description": "Payout plan, as the numeric `code` that `payoff_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "debt_type": { "description": "How BrokerPlus groups the debt for a debt consolidation analysis. A debt with no `debt_type` is left out of the analysis. Send null to clear.", "nullable": true, "type": "string", "enum": [ "second_mortgage", "heloc", "other_secured", "credit_card", "auto_loan", "personal_loc", "student_loan", "cra_tax", "other" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "liability", "description": "The type of this record. Always `liability`.", "type": "string", "enum": [ "liability" ] }, "id": { "type": "string", "description": "Stable identifier for the liability." }, "deal_id": { "type": "string", "description": "Deal this liability belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owes the debt, when one person owes it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the debt is secured by a property." }, "liability_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of debt, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of debt, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Liability type. `null` for real estate." }, "lender_name": { "nullable": true, "description": "Who the debt is owed to.", "type": "string" }, "from_credit_bureau": { "type": "boolean", "description": "`true` when the row came from a credit report rather than from the applicant. Consumer report data carries its own redistribution obligations. Check yours before you store or forward it." }, "pay_off": { "type": "boolean", "description": "`true` when the broker plans to pay the debt out at closing." }, "outstanding_balance": { "nullable": true, "description": "Balance owing, in dollars.", "type": "number" }, "monthly_repayment": { "nullable": true, "description": "Required monthly payment, in dollars.", "type": "number" }, "credit_limit": { "nullable": true, "description": "Credit limit, in dollars. Revolving debt only.", "type": "number" }, "net_rate": { "nullable": true, "description": "Rate on the debt as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "maturity_date": { "nullable": true, "description": "When the debt matures, as `YYYY-MM-DD`.", "type": "string" }, "debt_type": { "nullable": true, "description": "How BrokerPlus groups the debt for consolidation: `credit_card`, `auto_loan`, `personal_loc`, `student_loan`, `cra_tax`, `second_mortgage`, `heloc`, `other_secured`, or `other`. `null` when it was not grouped.", "type": "string" }, "secured_by_home": { "nullable": true, "description": "`true` when the broker marked this line of credit as secured against a home. The debt service ratios then count it at the higher of its stated payment and its balance repaid over 25 years at the qualifying rate. `null` when nobody has said.", "type": "boolean" }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "original_loan_amount": { "nullable": true, "description": "The amount first borrowed, in dollars. Secured debt only.", "type": "number" }, "closing_date": { "nullable": true, "description": "When the debt was taken out. Secured debt only.", "type": "string" }, "charge_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The charge position on title, e.g. second, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The charge position on title, e.g. second, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Charge type." }, "repayment_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is repaid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is repaid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Repayment type." }, "redemption_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Whether the debt is paid out, and how, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Whether the debt is paid out, and how, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Redemption status." }, "rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type." }, "payoff_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan." }, "source_deal_id": { "nullable": true, "description": "Another deal whose mortgage balance this row follows. Changes to that balance reach this row.", "type": "string" }, "property_id": { "nullable": true, "description": "The property this debt is the mortgage on. Resolve against `GET /deals/{id}/other-properties`.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "liability_type", "lender_name", "from_credit_bureau", "pay_off", "outstanding_balance", "monthly_repayment", "credit_limit", "net_rate", "maturity_date", "debt_type", "secured_by_home", "description", "original_loan_amount", "closing_date", "charge_type", "repayment_type", "redemption_status", "rate_type", "payoff_type", "source_deal_id", "property_id", "owner_contact_ids" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/liabilities/{liabilityId}": { "patch": { "operationId": "updateDealLiability", "summary": "Update a debt", "description": "Changes one debt. Send only the fields to change. A debt with `from_credit_bureau` set to `true` cannot be changed through the API.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "liabilityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "liability_type": { "description": "Kind of debt, as the numeric `code` that `liability_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 99 ] }, "lender_name": { "description": "Who the debt is owed to. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "pay_off": { "description": "`true` when the broker plans to pay the debt out at closing.", "type": "boolean" }, "outstanding_balance": { "description": "Balance owing, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_repayment": { "description": "Required monthly payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "credit_limit": { "description": "Credit limit, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "net_rate": { "description": "Rate on the debt as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "maturity_date": { "description": "When the debt matures. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "description": { "description": "Free-text detail. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "original_loan_amount": { "description": "The amount first borrowed, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "closing_date": { "description": "When the debt was taken out. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "charge_type": { "description": "Charge type, as the numeric `code` that `charge_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 99 ] }, "repayment_type": { "description": "Repayment type, as the numeric `code` that `repayment_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "redemption_status": { "description": "Redemption status, as the numeric `code` that `redemption_status` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 7 ] }, "rate_type": { "description": "Rate type, as the numeric `code` that `rate_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 2, 12, 99 ] }, "payoff_type": { "description": "Payout plan, as the numeric `code` that `payoff_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "debt_type": { "description": "How BrokerPlus groups the debt for a debt consolidation analysis. A debt with no `debt_type` is left out of the analysis. Send null to clear.", "nullable": true, "type": "string", "enum": [ "second_mortgage", "heloc", "other_secured", "credit_card", "auto_loan", "personal_loc", "student_loan", "cra_tax", "other" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "liability", "description": "The type of this record. Always `liability`.", "type": "string", "enum": [ "liability" ] }, "id": { "type": "string", "description": "Stable identifier for the liability." }, "deal_id": { "type": "string", "description": "Deal this liability belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owes the debt, when one person owes it.", "type": "string" }, "is_real_estate": { "type": "boolean", "description": "`true` when the debt is secured by a property." }, "liability_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Kind of debt, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Kind of debt, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Liability type. `null` for real estate." }, "lender_name": { "nullable": true, "description": "Who the debt is owed to.", "type": "string" }, "from_credit_bureau": { "type": "boolean", "description": "`true` when the row came from a credit report rather than from the applicant. Consumer report data carries its own redistribution obligations. Check yours before you store or forward it." }, "pay_off": { "type": "boolean", "description": "`true` when the broker plans to pay the debt out at closing." }, "outstanding_balance": { "nullable": true, "description": "Balance owing, in dollars.", "type": "number" }, "monthly_repayment": { "nullable": true, "description": "Required monthly payment, in dollars.", "type": "number" }, "credit_limit": { "nullable": true, "description": "Credit limit, in dollars. Revolving debt only.", "type": "number" }, "net_rate": { "nullable": true, "description": "Rate on the debt as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "maturity_date": { "nullable": true, "description": "When the debt matures, as `YYYY-MM-DD`.", "type": "string" }, "debt_type": { "nullable": true, "description": "How BrokerPlus groups the debt for consolidation: `credit_card`, `auto_loan`, `personal_loc`, `student_loan`, `cra_tax`, `second_mortgage`, `heloc`, `other_secured`, or `other`. `null` when it was not grouped.", "type": "string" }, "secured_by_home": { "nullable": true, "description": "`true` when the broker marked this line of credit as secured against a home. The debt service ratios then count it at the higher of its stated payment and its balance repaid over 25 years at the qualifying rate. `null` when nobody has said.", "type": "boolean" }, "description": { "nullable": true, "description": "Free-text detail the broker recorded.", "type": "string" }, "original_loan_amount": { "nullable": true, "description": "The amount first borrowed, in dollars. Secured debt only.", "type": "number" }, "closing_date": { "nullable": true, "description": "When the debt was taken out. Secured debt only.", "type": "string" }, "charge_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "The charge position on title, e.g. second, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "The charge position on title, e.g. second, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Charge type." }, "repayment_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is repaid, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is repaid, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Repayment type." }, "redemption_status": { "type": "object", "properties": { "code": { "nullable": true, "description": "Whether the debt is paid out, and how, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Whether the debt is paid out, and how, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Redemption status." }, "rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type." }, "payoff_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the debt is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the debt is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan." }, "source_deal_id": { "nullable": true, "description": "Another deal whose mortgage balance this row follows. Changes to that balance reach this row.", "type": "string" }, "property_id": { "nullable": true, "description": "The property this debt is the mortgage on. Resolve against `GET /deals/{id}/other-properties`.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this row, as contact ids. `contact_id` is the first of them." } }, "required": [ "object", "id", "deal_id", "contact_id", "is_real_estate", "liability_type", "lender_name", "from_credit_bureau", "pay_off", "outstanding_balance", "monthly_repayment", "credit_limit", "net_rate", "maturity_date", "debt_type", "secured_by_home", "description", "original_loan_amount", "closing_date", "charge_type", "repayment_type", "redemption_status", "rate_type", "payoff_type", "source_deal_id", "property_id", "owner_contact_ids" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The debt came from a credit report (FROM_CREDIT_BUREAU).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealLiability", "summary": "Remove a debt", "description": "Deletes one debt. A debt with `from_credit_bureau` set to `true` cannot be deleted through the API.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "liabilityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The debt came from a credit report (FROM_CREDIT_BUREAU).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/other-properties": { "get": { "operationId": "listDealOtherProperties", "summary": "List the other properties the applicants own", "description": "Every property the applicants own other than the one being mortgaged, with its value, its mortgage, and its rent. Rates are PERCENT (`5.49` means 5.49%).", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "other_property", "description": "The type of this record. Always `other_property`.", "type": "string", "enum": [ "other_property" ] }, "id": { "type": "string", "description": "Stable identifier for the property." }, "deal_id": { "type": "string", "description": "Deal this property belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the property, when one person owns it.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this property, as contact ids. `contact_id` is the first of them." }, "property_use": { "type": "string", "enum": [ "rental", "second_home", "other", "investment", "vacation", "owner_occupied", "owner_occupied_rental", "unoccupied" ], "description": "What the property is used for, e.g. `rental`." }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "value": { "type": "number", "description": "Value, in dollars. The value the broker entered, else the estimate BrokerPlus holds, else 0." }, "original_price": { "nullable": true, "description": "What the applicant paid, in dollars.", "type": "number" }, "original_date": { "nullable": true, "description": "When the applicant bought it.", "type": "string" }, "annual_property_tax": { "nullable": true, "description": "Annual property tax, in dollars.", "type": "number" }, "monthly_condo_fees": { "nullable": true, "description": "Monthly condo fees, in dollars.", "type": "number" }, "monthly_heating_amount": { "nullable": true, "description": "Monthly heating cost, in dollars.", "type": "number" }, "still_mortgaged": { "type": "boolean", "description": "`true` when a mortgage is still on the property." }, "mortgage_balance": { "nullable": true, "description": "Balance owing on the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on the mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly mortgage payment, in dollars.", "type": "number" }, "mortgage_lender": { "nullable": true, "description": "Who holds the mortgage.", "type": "string" }, "mortgage_maturity_date": { "nullable": true, "description": "When the mortgage term ends.", "type": "string" }, "payoff": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the mortgage is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the mortgage is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan. `null` when the mortgage stays." }, "include_in_tds": { "type": "boolean", "description": "`true` when the property's costs count in the total debt service ratio." }, "monthly_rental_income": { "nullable": true, "description": "Monthly rent, in dollars.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "value_estimate": { "nullable": true, "description": "The value estimate BrokerPlus holds, in dollars, before any broker figure.", "type": "number" }, "value_source": { "nullable": true, "description": "Where the estimate came from: `houski`, `finmo`, `manual`, `csv`, or `client`.", "type": "string" }, "condo_fees_include_heating": { "type": "boolean", "description": "`true` when the condo fee already covers heat." }, "condo_fee_tds_pct": { "nullable": true, "description": "The share of the condo fee that counts toward the total debt service ratio, as a PERCENT from 0 to 100. `null` counts the whole fee.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mortgage_rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type of the mortgage on this property." }, "mortgage_payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the mortgage payment is made, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the mortgage payment is made, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency of the mortgage on this property." }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_hydro_costs": { "nullable": true, "description": "Monthly hydro cost, in dollars.", "type": "number" }, "monthly_insurance_costs": { "nullable": true, "description": "Monthly insurance cost, in dollars.", "type": "number" }, "monthly_management_costs": { "nullable": true, "description": "Monthly property management cost, in dollars.", "type": "number" }, "monthly_repairs_costs": { "nullable": true, "description": "Monthly repairs cost, in dollars.", "type": "number" }, "monthly_interest_costs": { "nullable": true, "description": "Monthly interest cost, in dollars.", "type": "number" }, "monthly_other_costs": { "nullable": true, "description": "Other monthly operating costs, in dollars.", "type": "number" }, "monthly_fees_offset": { "nullable": true, "description": "Dollars of the monthly condo fee left out of the ratios. Separate from `condo_fee_tds_pct`.", "type": "number" } }, "required": [ "object", "id", "deal_id", "contact_id", "owner_contact_ids", "property_use", "street_number", "street_name", "unit", "city", "province", "postal_code", "value", "original_price", "original_date", "annual_property_tax", "monthly_condo_fees", "monthly_heating_amount", "still_mortgaged", "mortgage_balance", "interest_rate", "monthly_payment", "mortgage_lender", "mortgage_maturity_date", "payoff", "include_in_tds", "monthly_rental_income", "rental_offset_pct", "street_type", "street_direction", "value_estimate", "value_source", "condo_fees_include_heating", "condo_fee_tds_pct", "mortgage_rate_type", "mortgage_payment_frequency", "rental_calc_type", "monthly_hydro_costs", "monthly_insurance_costs", "monthly_management_costs", "monthly_repairs_costs", "monthly_interest_costs", "monthly_other_costs", "monthly_fees_offset" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealOtherProperty", "summary": "Add another property", "description": "Adds one property the applicants own other than the one being mortgaged. `property_use` is required. The ratios on the application include the property's costs on the next read.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "property_use": { "type": "string", "enum": [ "rental", "second_home", "other", "investment", "vacation", "owner_occupied", "owner_occupied_rental", "unoccupied" ], "description": "What the property is used for, e.g. `rental`." }, "street_number": { "description": "Street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "street_name": { "description": "Street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 }, "unit": { "description": "Unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "city": { "description": "City or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "province": { "description": "Province, as the two-letter code that `province` returns on read, e.g. `ON`, or as the numeric province code. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] }, { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] } ] }, "postal_code": { "description": "Postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "value": { "description": "Value the broker states, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "original_price": { "description": "What the applicant paid, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "original_date": { "description": "When the applicant bought it. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "annual_property_tax": { "description": "Annual property tax, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_condo_fees": { "description": "Monthly condo fees, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_heating_amount": { "description": "Monthly heating cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "still_mortgaged": { "description": "`true` when a mortgage is still on the property.", "type": "boolean" }, "mortgage_balance": { "description": "Balance owing on the mortgage, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "interest_rate": { "description": "Rate on the mortgage as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "monthly_payment": { "description": "Monthly mortgage payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "mortgage_lender": { "description": "Who holds the mortgage. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "mortgage_maturity_date": { "description": "When the mortgage term ends. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "payoff": { "description": "How the mortgage is paid out at closing, as the numeric `code` that `payoff` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "include_in_tds": { "description": "`true` when the property's costs count in the total debt service ratio.", "type": "boolean" }, "monthly_rental_income": { "description": "Monthly rent, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "rental_offset_pct": { "description": "The share of rent that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "street_type": { "description": "Street type, as the numeric `code` that `street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "street_direction": { "description": "Street direction, as the numeric `code` that `street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "condo_fees_include_heating": { "description": "`true` when the condo fee already covers heat.", "type": "boolean" }, "condo_fee_tds_pct": { "description": "The share of the condo fee that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "mortgage_rate_type": { "description": "Rate type of the mortgage, as the numeric `code` that `mortgage_rate_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 2, 12, 99 ] }, "mortgage_payment_frequency": { "description": "Mortgage payment frequency, as the numeric `code` that `mortgage_payment_frequency` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ] }, "rental_calc_type": { "description": "Rental calculation method, as the numeric `code` that `rental_calc_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "monthly_hydro_costs": { "description": "Monthly hydro cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_insurance_costs": { "description": "Monthly insurance cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_management_costs": { "description": "Monthly property management cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_repairs_costs": { "description": "Monthly repairs cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_interest_costs": { "description": "Monthly interest cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_other_costs": { "description": "Other monthly operating costs, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_fees_offset": { "description": "Monthly condo fee left out of the ratios, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "property_use" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "other_property", "description": "The type of this record. Always `other_property`.", "type": "string", "enum": [ "other_property" ] }, "id": { "type": "string", "description": "Stable identifier for the property." }, "deal_id": { "type": "string", "description": "Deal this property belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the property, when one person owns it.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this property, as contact ids. `contact_id` is the first of them." }, "property_use": { "type": "string", "enum": [ "rental", "second_home", "other", "investment", "vacation", "owner_occupied", "owner_occupied_rental", "unoccupied" ], "description": "What the property is used for, e.g. `rental`." }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "value": { "type": "number", "description": "Value, in dollars. The value the broker entered, else the estimate BrokerPlus holds, else 0." }, "original_price": { "nullable": true, "description": "What the applicant paid, in dollars.", "type": "number" }, "original_date": { "nullable": true, "description": "When the applicant bought it.", "type": "string" }, "annual_property_tax": { "nullable": true, "description": "Annual property tax, in dollars.", "type": "number" }, "monthly_condo_fees": { "nullable": true, "description": "Monthly condo fees, in dollars.", "type": "number" }, "monthly_heating_amount": { "nullable": true, "description": "Monthly heating cost, in dollars.", "type": "number" }, "still_mortgaged": { "type": "boolean", "description": "`true` when a mortgage is still on the property." }, "mortgage_balance": { "nullable": true, "description": "Balance owing on the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on the mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly mortgage payment, in dollars.", "type": "number" }, "mortgage_lender": { "nullable": true, "description": "Who holds the mortgage.", "type": "string" }, "mortgage_maturity_date": { "nullable": true, "description": "When the mortgage term ends.", "type": "string" }, "payoff": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the mortgage is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the mortgage is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan. `null` when the mortgage stays." }, "include_in_tds": { "type": "boolean", "description": "`true` when the property's costs count in the total debt service ratio." }, "monthly_rental_income": { "nullable": true, "description": "Monthly rent, in dollars.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "value_estimate": { "nullable": true, "description": "The value estimate BrokerPlus holds, in dollars, before any broker figure.", "type": "number" }, "value_source": { "nullable": true, "description": "Where the estimate came from: `houski`, `finmo`, `manual`, `csv`, or `client`.", "type": "string" }, "condo_fees_include_heating": { "type": "boolean", "description": "`true` when the condo fee already covers heat." }, "condo_fee_tds_pct": { "nullable": true, "description": "The share of the condo fee that counts toward the total debt service ratio, as a PERCENT from 0 to 100. `null` counts the whole fee.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mortgage_rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type of the mortgage on this property." }, "mortgage_payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the mortgage payment is made, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the mortgage payment is made, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency of the mortgage on this property." }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_hydro_costs": { "nullable": true, "description": "Monthly hydro cost, in dollars.", "type": "number" }, "monthly_insurance_costs": { "nullable": true, "description": "Monthly insurance cost, in dollars.", "type": "number" }, "monthly_management_costs": { "nullable": true, "description": "Monthly property management cost, in dollars.", "type": "number" }, "monthly_repairs_costs": { "nullable": true, "description": "Monthly repairs cost, in dollars.", "type": "number" }, "monthly_interest_costs": { "nullable": true, "description": "Monthly interest cost, in dollars.", "type": "number" }, "monthly_other_costs": { "nullable": true, "description": "Other monthly operating costs, in dollars.", "type": "number" }, "monthly_fees_offset": { "nullable": true, "description": "Dollars of the monthly condo fee left out of the ratios. Separate from `condo_fee_tds_pct`.", "type": "number" } }, "required": [ "object", "id", "deal_id", "contact_id", "owner_contact_ids", "property_use", "street_number", "street_name", "unit", "city", "province", "postal_code", "value", "original_price", "original_date", "annual_property_tax", "monthly_condo_fees", "monthly_heating_amount", "still_mortgaged", "mortgage_balance", "interest_rate", "monthly_payment", "mortgage_lender", "mortgage_maturity_date", "payoff", "include_in_tds", "monthly_rental_income", "rental_offset_pct", "street_type", "street_direction", "value_estimate", "value_source", "condo_fees_include_heating", "condo_fee_tds_pct", "mortgage_rate_type", "mortgage_payment_frequency", "rental_calc_type", "monthly_hydro_costs", "monthly_insurance_costs", "monthly_management_costs", "monthly_repairs_costs", "monthly_interest_costs", "monthly_other_costs", "monthly_fees_offset" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/other-properties/{propertyId}": { "patch": { "operationId": "updateDealOtherProperty", "summary": "Update another property", "description": "Changes one property. Send only the fields to change. A change to `payoff` also changes the paired mortgage debt, when the property has one.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "description": "The applicant who holds the row, as a contact id. Ignored when `owner_contact_ids` is sent.", "nullable": true, "type": "string" }, "owner_contact_ids": { "description": "Every applicant who holds the row, as contact ids. A contact that is not an applicant on this deal is ignored. Leave it out to keep the owners as they are.", "maxItems": 20, "type": "array", "items": { "type": "string" } }, "property_use": { "type": "string", "enum": [ "rental", "second_home", "other", "investment", "vacation", "owner_occupied", "owner_occupied_rental", "unoccupied" ], "description": "What the property is used for, e.g. `rental`." }, "street_number": { "description": "Street number. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "street_name": { "description": "Street name. Send null to clear.", "nullable": true, "type": "string", "maxLength": 500 }, "unit": { "description": "Unit or suite. Send null to clear.", "nullable": true, "type": "string", "maxLength": 50 }, "city": { "description": "City or town. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "province": { "description": "Province, as the two-letter code that `province` returns on read, e.g. `ON`, or as the numeric province code. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ] }, { "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130 ] } ] }, "postal_code": { "description": "Postal code. Send null to clear.", "nullable": true, "type": "string", "maxLength": 20 }, "value": { "description": "Value the broker states, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "original_price": { "description": "What the applicant paid, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "original_date": { "description": "When the applicant bought it. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "annual_property_tax": { "description": "Annual property tax, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_condo_fees": { "description": "Monthly condo fees, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_heating_amount": { "description": "Monthly heating cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "still_mortgaged": { "description": "`true` when a mortgage is still on the property.", "type": "boolean" }, "mortgage_balance": { "description": "Balance owing on the mortgage, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "interest_rate": { "description": "Rate on the mortgage as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "monthly_payment": { "description": "Monthly mortgage payment, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "mortgage_lender": { "description": "Who holds the mortgage. Send null to clear.", "nullable": true, "type": "string", "maxLength": 200 }, "mortgage_maturity_date": { "description": "When the mortgage term ends. Accepts YYYY-MM-DD or an ISO 8601 timestamp. Send null to clear.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] }, "payoff": { "description": "How the mortgage is paid out at closing, as the numeric `code` that `payoff` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "include_in_tds": { "description": "`true` when the property's costs count in the total debt service ratio.", "type": "boolean" }, "monthly_rental_income": { "description": "Monthly rent, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "rental_offset_pct": { "description": "The share of rent that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "street_type": { "description": "Street type, as the numeric `code` that `street_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 260, 270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440, 450, 460, 470, 480, 490, 500, 510, 520, 530, 540, 550, 560, 570, 590, 600, 610, 620, 630, 640, 650, 660, 670, 680, 690, 700, 710, 720, 730, 740, 750, 760, 770, 780, 790, 800, 810, 820, 830, 840, 850, 860, 870, 880, 890, 900, 910, 920, 930, 940, 950, 960, 970, 980, 990, 1000, 1010, 1020, 1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100, 1110, 1120, 1130, 1140, 1150, 1160, 1170, 1180, 1190, 1200, 1210, 1220, 1230, 1240, 1250, 1260, 1270, 1280, 1290, 1300, 1310, 1320, 1330, 1340, 1350, 1360, 1370, 1380, 1390, 1400, 1410, 1420, 1430, 1440, 1450, 1460, 1470, 1480, 1490, 1500, 1510, 1520, 1530, 1540, 1550, 1560, 1570, 1580, 1590, 1600, 1610, 1620, 1630, 1640, 1650, 1660, 1670, 1680, 1690, 1700, 1710, 1720, 1730, 1740, 1750, 1760, 1770, 1780, 1790, 1800, 1810, 1820, 1830 ] }, "street_direction": { "description": "Street direction, as the numeric `code` that `street_direction` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "condo_fees_include_heating": { "description": "`true` when the condo fee already covers heat.", "type": "boolean" }, "condo_fee_tds_pct": { "description": "The share of the condo fee that counts, as a PERCENT from 0 to 100. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "mortgage_rate_type": { "description": "Rate type of the mortgage, as the numeric `code` that `mortgage_rate_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 0, 2, 12, 99 ] }, "mortgage_payment_frequency": { "description": "Mortgage payment frequency, as the numeric `code` that `mortgage_payment_frequency` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2, 4, 12, 24, 26, 52 ] }, "rental_calc_type": { "description": "Rental calculation method, as the numeric `code` that `rental_calc_type` returns on read. Send null to clear.", "nullable": true, "type": "number", "enum": [ 1, 2 ] }, "monthly_hydro_costs": { "description": "Monthly hydro cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_insurance_costs": { "description": "Monthly insurance cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_management_costs": { "description": "Monthly property management cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_repairs_costs": { "description": "Monthly repairs cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_interest_costs": { "description": "Monthly interest cost, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_other_costs": { "description": "Other monthly operating costs, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "monthly_fees_offset": { "description": "Monthly condo fee left out of the ratios, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "other_property", "description": "The type of this record. Always `other_property`.", "type": "string", "enum": [ "other_property" ] }, "id": { "type": "string", "description": "Stable identifier for the property." }, "deal_id": { "type": "string", "description": "Deal this property belongs to." }, "contact_id": { "nullable": true, "description": "Contact who owns the property, when one person owns it.", "type": "string" }, "owner_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Every applicant who holds this property, as contact ids. `contact_id` is the first of them." }, "property_use": { "type": "string", "enum": [ "rental", "second_home", "other", "investment", "vacation", "owner_occupied", "owner_occupied_rental", "unoccupied" ], "description": "What the property is used for, e.g. `rental`." }, "street_number": { "nullable": true, "description": "Street number.", "type": "string" }, "street_name": { "nullable": true, "description": "Street name.", "type": "string" }, "unit": { "nullable": true, "description": "Unit or suite.", "type": "string" }, "city": { "nullable": true, "description": "City or town.", "type": "string" }, "province": { "nullable": true, "description": "Two-letter province code, e.g. `ON`.", "type": "string" }, "postal_code": { "nullable": true, "description": "Postal code.", "type": "string" }, "value": { "type": "number", "description": "Value, in dollars. The value the broker entered, else the estimate BrokerPlus holds, else 0." }, "original_price": { "nullable": true, "description": "What the applicant paid, in dollars.", "type": "number" }, "original_date": { "nullable": true, "description": "When the applicant bought it.", "type": "string" }, "annual_property_tax": { "nullable": true, "description": "Annual property tax, in dollars.", "type": "number" }, "monthly_condo_fees": { "nullable": true, "description": "Monthly condo fees, in dollars.", "type": "number" }, "monthly_heating_amount": { "nullable": true, "description": "Monthly heating cost, in dollars.", "type": "number" }, "still_mortgaged": { "type": "boolean", "description": "`true` when a mortgage is still on the property." }, "mortgage_balance": { "nullable": true, "description": "Balance owing on the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate on the mortgage as a PERCENT, e.g. `5.49` means 5.49%. Not a fraction.", "type": "number" }, "monthly_payment": { "nullable": true, "description": "Monthly mortgage payment, in dollars.", "type": "number" }, "mortgage_lender": { "nullable": true, "description": "Who holds the mortgage.", "type": "string" }, "mortgage_maturity_date": { "nullable": true, "description": "When the mortgage term ends.", "type": "string" }, "payoff": { "type": "object", "properties": { "code": { "nullable": true, "description": "How the mortgage is paid out at closing, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How the mortgage is paid out at closing, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payout plan. `null` when the mortgage stays." }, "include_in_tds": { "type": "boolean", "description": "`true` when the property's costs count in the total debt service ratio." }, "monthly_rental_income": { "nullable": true, "description": "Monthly rent, in dollars.", "type": "number" }, "rental_offset_pct": { "nullable": true, "description": "The share of rent that counts, as a PERCENT from 0 to 100.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "street_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street type, e.g. Avenue, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street type, e.g. Avenue, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street type." }, "street_direction": { "type": "object", "properties": { "code": { "nullable": true, "description": "Street direction, e.g. NW, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Street direction, e.g. NW, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Street direction." }, "value_estimate": { "nullable": true, "description": "The value estimate BrokerPlus holds, in dollars, before any broker figure.", "type": "number" }, "value_source": { "nullable": true, "description": "Where the estimate came from: `houski`, `finmo`, `manual`, `csv`, or `client`.", "type": "string" }, "condo_fees_include_heating": { "type": "boolean", "description": "`true` when the condo fee already covers heat." }, "condo_fee_tds_pct": { "nullable": true, "description": "The share of the condo fee that counts toward the total debt service ratio, as a PERCENT from 0 to 100. `null` counts the whole fee.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mortgage_rate_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "Fixed, variable, or another rate structure, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "Fixed, variable, or another rate structure, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rate type of the mortgage on this property." }, "mortgage_payment_frequency": { "type": "object", "properties": { "code": { "nullable": true, "description": "How often the mortgage payment is made, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How often the mortgage payment is made, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Payment frequency of the mortgage on this property." }, "rental_calc_type": { "type": "object", "properties": { "code": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, as the lender's numeric code.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "nullable": true, "description": "How rent enters the ratios: offset against costs, or added to income, in words. `Unknown` if the code is one we cannot name.", "type": "string" } }, "required": [ "code", "label" ], "additionalProperties": false, "description": "Rental calculation method." }, "monthly_hydro_costs": { "nullable": true, "description": "Monthly hydro cost, in dollars.", "type": "number" }, "monthly_insurance_costs": { "nullable": true, "description": "Monthly insurance cost, in dollars.", "type": "number" }, "monthly_management_costs": { "nullable": true, "description": "Monthly property management cost, in dollars.", "type": "number" }, "monthly_repairs_costs": { "nullable": true, "description": "Monthly repairs cost, in dollars.", "type": "number" }, "monthly_interest_costs": { "nullable": true, "description": "Monthly interest cost, in dollars.", "type": "number" }, "monthly_other_costs": { "nullable": true, "description": "Other monthly operating costs, in dollars.", "type": "number" }, "monthly_fees_offset": { "nullable": true, "description": "Dollars of the monthly condo fee left out of the ratios. Separate from `condo_fee_tds_pct`.", "type": "number" } }, "required": [ "object", "id", "deal_id", "contact_id", "owner_contact_ids", "property_use", "street_number", "street_name", "unit", "city", "province", "postal_code", "value", "original_price", "original_date", "annual_property_tax", "monthly_condo_fees", "monthly_heating_amount", "still_mortgaged", "mortgage_balance", "interest_rate", "monthly_payment", "mortgage_lender", "mortgage_maturity_date", "payoff", "include_in_tds", "monthly_rental_income", "rental_offset_pct", "street_type", "street_direction", "value_estimate", "value_source", "condo_fees_include_heating", "condo_fee_tds_pct", "mortgage_rate_type", "mortgage_payment_frequency", "rental_calc_type", "monthly_hydro_costs", "monthly_insurance_costs", "monthly_management_costs", "monthly_repairs_costs", "monthly_interest_costs", "monthly_other_costs", "monthly_fees_offset" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealOtherProperty", "summary": "Remove another property", "description": "Deletes one property and its valuation history.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/other-properties/{propertyId}/valuations": { "get": { "operationId": "getDealOtherPropertyValuations", "summary": "Get the valuation history of another property", "description": "Every valuation BrokerPlus holds for one other property, newest first, and how the estimate changed over the last year. `change_12mo.change_pct` is a PERCENT (`4.5` means 4.5%).", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "property_id": { "type": "string", "description": "The other property." }, "deal_id": { "type": "string", "description": "The deal the property is on." }, "change_12mo": { "nullable": true, "description": "How the estimate changed over the last year. Null until there are two estimates to compare.", "type": "object", "properties": { "from": { "type": "number", "description": "The estimate about one year before the latest one, in dollars." }, "to": { "type": "number", "description": "The latest estimate, in dollars." }, "change_pct": { "type": "number", "description": "The change from `from` to `to`, as a PERCENT. `4.5` means the value went up 4.5%." } }, "required": [ "from", "to", "change_pct" ], "additionalProperties": false }, "valuations": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "other_property_valuation", "description": "The type of this record. Always `other_property_valuation`.", "type": "string", "enum": [ "other_property_valuation" ] }, "id": { "type": "string", "description": "Stable identifier for the valuation." }, "property_id": { "type": "string", "description": "The other property that was valued." }, "valuation_date": { "type": "string", "description": "When the property was valued, as an ISO 8601 timestamp." }, "estimated_value": { "nullable": true, "description": "The estimated market value, in dollars. Null if none was given.", "type": "number" }, "assessment_value": { "nullable": true, "description": "The municipal assessment value, in dollars. Null if none was given.", "type": "number" }, "source": { "type": "string", "enum": [ "houski", "finmo", "manual", "csv", "client" ], "description": "Where the value came from: `houski` from the valuation service, `finmo` from a Finmo application, `manual` from the broker, `csv` from an import, `client` from the client." }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the valuation." } }, "required": [ "object", "id", "property_id", "valuation_date", "estimated_value", "assessment_value", "source", "created_at" ], "additionalProperties": false }, "description": "Every valuation of the property, newest first, at most 100." } }, "required": [ "property_id", "deal_id", "change_12mo", "valuations" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/property-valuations": { "get": { "operationId": "getDealPropertyValuations", "summary": "Get the value history of the deal's property", "description": "Every valuation BrokerPlus holds for the property the deal's mortgage is on, newest first. This is the home value trend on the client's equity report. BrokerPlus adds a valuation each month while the client gets reports. The value the opportunity shows can differ when the broker set their own in `property_value`.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal whose property the history is for." }, "valuations": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "property_valuation", "description": "The type of this record. Always `property_valuation`.", "type": "string", "enum": [ "property_valuation" ] }, "id": { "type": "string", "description": "Stable identifier for the valuation." }, "deal_id": { "type": "string", "description": "The deal whose property was valued." }, "valuation_date": { "type": "string", "description": "When the property was valued, as an ISO 8601 timestamp." }, "estimated_value": { "nullable": true, "description": "The estimated market value, in dollars. Null if none was given.", "type": "number" }, "assessment_value": { "nullable": true, "description": "The municipal assessment value, in dollars. Null if none was given.", "type": "number" }, "source": { "type": "string", "enum": [ "houski", "finmo", "manual", "csv", "client" ], "description": "Where the value came from: `houski` from the valuation service, `finmo` from a Finmo application, `manual` from the broker, `csv` from an import, `client` from the client." }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the valuation." } }, "required": [ "object", "id", "deal_id", "valuation_date", "estimated_value", "assessment_value", "source", "created_at" ], "additionalProperties": false }, "description": "Every valuation of the deal's property, newest first, at most 100." } }, "required": [ "deal_id", "valuations" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/other-properties/{propertyId}/refresh-valuation": { "post": { "operationId": "refreshDealOtherPropertyValuation", "summary": "Ask for a new valuation of another property", "description": "Asks the valuation service for a new estimate of one other property, the same as the refresh button in BrokerPlus. The valuation runs in the background, so the response is 202. Read the valuation history again in a minute to see the new value. The property must have a street address.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "other_property_valuation_refresh", "description": "The type of this record. Always `other_property_valuation_refresh`.", "type": "string", "enum": [ "other_property_valuation_refresh" ] }, "id": { "type": "string", "description": "The other property that a new valuation was asked for." }, "deal_id": { "type": "string", "description": "The deal the property is on." }, "queued": { "type": "boolean", "description": "Always `true`. The valuation runs in the background: read the history again in a minute to see the new value." } }, "required": [ "object", "id", "deal_id", "queued" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The property has no street address (NO_ADDRESS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consolidation-analyses": { "get": { "operationId": "listDealConsolidationAnalyses", "summary": "List debt consolidation analyses", "description": "The debt consolidation analyses run on a deal, newest first. The first one is the deal's current analysis. An analysis never changes: run a new one to update it. Every rate is a PERCENT (`4.59` means 4.59%).", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "consolidation_analysis", "description": "The type of this record. Always `consolidation_analysis`.", "type": "string", "enum": [ "consolidation_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "deal_id": { "type": "string", "description": "The deal that the analysis is for." }, "recommendation": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage", "not_viable", "not_recommended" ], "description": "The option BrokerPlus recommends, or `not_viable` when no option works for the client." }, "recommendation_tier": { "nullable": true, "description": "How strongly BrokerPlus recommends the option. Null on an analysis saved before tiers existed.", "type": "string", "enum": [ "strong", "recommended", "conditional", "unlikely", "not_recommended" ] }, "recommendation_text": { "nullable": true, "description": "The recommendation in words, as the broker sees it.", "type": "string" }, "monthly_savings": { "nullable": true, "description": "How much less the client pays each month with the recommended option, in dollars.", "type": "number" }, "recommended_option_index": { "nullable": true, "description": "The position of the recommended option in `options`, from 0. Null when no option is recommended.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status_quo": { "nullable": true, "description": "The client's position if nothing changes. Null on an incomplete analysis: run it again.", "type": "object", "properties": { "mortgage_payment": { "type": "number", "description": "The client's monthly mortgage payment now, in dollars." }, "total_debt_payments": { "type": "number", "description": "The client's monthly payments on their other debts now, in dollars." }, "total_monthly_outflow": { "type": "number", "description": "The mortgage and the debt payments together, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years if nothing changes." }, "longest_payoff_years": { "type": "number", "description": "How many years the slowest debt takes to pay off." }, "debt_balance": { "type": "number", "description": "What the client owes on their other debts, in dollars." }, "debt_rate_pct": { "type": "number", "description": "The blended rate on the other debts, as a PERCENT." }, "debt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many other debts the client has." }, "has_negative_amortization_debt": { "type": "boolean", "description": "`true` when a payment on a debt does not cover its interest, so the balance grows." } }, "required": [ "mortgage_payment", "total_debt_payments", "total_monthly_outflow", "total_interest_5yr", "longest_payoff_years", "debt_balance", "debt_rate_pct", "debt_count", "has_negative_amortization_debt" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage" ], "description": "How the debts are paid out: `refinance` into a new mortgage, `heloc` from a home equity line of credit, or `reverse_mortgage`." }, "subject": { "nullable": true, "description": "Which property the option borrows against: `subject` the client's home, `other_property` another property they own, `blanket` several properties together.", "type": "string", "enum": [ "subject", "other_property", "blanket" ] }, "property_id": { "nullable": true, "description": "The other property the option borrows against, when `subject` is `other_property`.", "type": "string" }, "eligible": { "type": "boolean", "description": "`true` when the client qualifies for this option." }, "reason": { "nullable": true, "description": "Why the client does not qualify. Null when `eligible` is `true`.", "type": "string" }, "new_monthly_payment": { "type": "number", "description": "The client's monthly payment with this option, in dollars." }, "monthly_savings": { "type": "number", "description": "How much less the client pays each month than now, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years with this option, in dollars." }, "interest_saved_5yr": { "type": "number", "description": "The interest the client saves over five years, in dollars." }, "break_even_months": { "type": "number", "description": "How many months the savings take to pay back the cost of the option." }, "new_ltv_pct": { "type": "number", "description": "The loan-to-value ratio after the option, as a PERCENT. `80` means 80%." }, "new_mortgage_balance": { "nullable": true, "description": "The new mortgage balance, in dollars.", "type": "number" }, "new_mortgage_rate_pct": { "nullable": true, "description": "The rate on the new mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "penalty_cost": { "nullable": true, "description": "The penalty to break the current mortgage, in dollars.", "type": "number" }, "penalty_unknown": { "type": "boolean", "description": "`true` when BrokerPlus does not know the penalty, so the figures leave it out." }, "secured_debt_payout": { "nullable": true, "description": "The secured debts on the property that the option pays out, in dollars.", "type": "number" }, "heloc_draw": { "nullable": true, "description": "How much the client draws on the line of credit, in dollars.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The rate on the line of credit, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_interest_only_payment": { "nullable": true, "description": "The monthly interest-only payment on the line of credit, in dollars.", "type": "number" }, "heloc_principal_and_interest_payment": { "nullable": true, "description": "The monthly payment that also pays down the line of credit, in dollars.", "type": "number" }, "equity_at_5yr": { "nullable": true, "description": "The client's equity after five years, in dollars.", "type": "number" }, "equity_at_10yr": { "nullable": true, "description": "The client's equity after ten years, in dollars.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The rate on the reverse mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "requires_rental_qualification": { "type": "boolean", "description": "`true` when the lender must qualify the client on the rental income of the property." } }, "required": [ "type", "subject", "property_id", "eligible", "reason", "new_monthly_payment", "monthly_savings", "total_interest_5yr", "interest_saved_5yr", "break_even_months", "new_ltv_pct", "new_mortgage_balance", "new_mortgage_rate_pct", "penalty_cost", "penalty_unknown", "secured_debt_payout", "heloc_draw", "heloc_rate_pct", "heloc_interest_only_payment", "heloc_principal_and_interest_payment", "equity_at_5yr", "equity_at_10yr", "reverse_mortgage_rate_pct", "requires_rental_qualification" ], "additionalProperties": false }, "description": "Every option BrokerPlus compared." }, "default_rates": { "type": "object", "properties": { "refinance_rate_pct": { "nullable": true, "description": "The refinance rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "refinance_rate_pct", "heloc_rate_pct" ], "additionalProperties": false, "description": "The rates the analysis uses by default." }, "inputs": { "nullable": true, "description": "The figures the analysis read from the deal and the rates it used.", "type": "object", "properties": { "mortgage_balance": { "type": "number", "description": "The balance on the current mortgage, in dollars." }, "mortgage_rate_pct": { "type": "number", "description": "The rate on the current mortgage, as a PERCENT." }, "mortgage_payment": { "type": "number", "description": "The monthly payment on the current mortgage, in dollars." }, "property_value": { "type": "number", "description": "The value of the client's home, in dollars." }, "remaining_term_months": { "type": "number", "description": "The months left in the current mortgage term." }, "amortization_months": { "type": "number", "description": "The amortization used for the new mortgage, in months." }, "penalty": { "type": "number", "description": "The penalty to break the current mortgage, in dollars." }, "new_mortgage_rate_pct": { "nullable": true, "description": "The refinance rate the analysis used, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The reverse mortgage rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "rental_heloc_rate_pct": { "nullable": true, "description": "The rental line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "mortgage_balance", "mortgage_rate_pct", "mortgage_payment", "property_value", "remaining_term_months", "amortization_months", "penalty", "new_mortgage_rate_pct", "heloc_rate_pct", "reverse_mortgage_rate_pct", "rental_heloc_rate_pct" ], "additionalProperties": false }, "created_at": { "type": "string", "description": "When the analysis ran. An analysis never changes: run a new one to update it." } }, "required": [ "object", "id", "deal_id", "recommendation", "recommendation_tier", "recommendation_text", "monthly_savings", "recommended_option_index", "status_quo", "options", "default_rates", "inputs", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealConsolidationAnalysis", "summary": "Run a debt consolidation analysis", "description": "Compares paying out the client's debts with a refinance, a home equity line of credit, or a reverse mortgage, the same as the Debts tab in BrokerPlus. The analysis reads every debt on the deal that has a `debt_type`, the other properties, and the value and balance on the deal's opportunity. Send a rate to replace the default for that option. BrokerPlus sends nothing to the client.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_mortgage_rate_pct": { "description": "The rate on the new mortgage for a refinance, as a PERCENT from 0.01 to 25. `4.59` means 4.59%. Leave it out to use the default.", "type": "number", "minimum": 0.01, "maximum": 25 }, "heloc_rate_pct": { "description": "The rate on a home equity line of credit, as a PERCENT from 0.01 to 25. `4.59` means 4.59%. Leave it out to use the default.", "type": "number", "minimum": 0.01, "maximum": 25 }, "reverse_mortgage_rate_pct": { "description": "The rate on a reverse mortgage, as a PERCENT from 0.01 to 25. `4.59` means 4.59%. Leave it out to use the default.", "type": "number", "minimum": 0.01, "maximum": 25 }, "rental_heloc_rate_pct": { "description": "The rate on a line of credit against a rental property, as a PERCENT from 0.01 to 25. `4.59` means 4.59%. Leave it out to use the default.", "type": "number", "minimum": 0.01, "maximum": 25 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consolidation_analysis", "description": "The type of this record. Always `consolidation_analysis`.", "type": "string", "enum": [ "consolidation_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "deal_id": { "type": "string", "description": "The deal that the analysis is for." }, "recommendation": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage", "not_viable", "not_recommended" ], "description": "The option BrokerPlus recommends, or `not_viable` when no option works for the client." }, "recommendation_tier": { "nullable": true, "description": "How strongly BrokerPlus recommends the option. Null on an analysis saved before tiers existed.", "type": "string", "enum": [ "strong", "recommended", "conditional", "unlikely", "not_recommended" ] }, "recommendation_text": { "nullable": true, "description": "The recommendation in words, as the broker sees it.", "type": "string" }, "monthly_savings": { "nullable": true, "description": "How much less the client pays each month with the recommended option, in dollars.", "type": "number" }, "recommended_option_index": { "nullable": true, "description": "The position of the recommended option in `options`, from 0. Null when no option is recommended.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status_quo": { "nullable": true, "description": "The client's position if nothing changes. Null on an incomplete analysis: run it again.", "type": "object", "properties": { "mortgage_payment": { "type": "number", "description": "The client's monthly mortgage payment now, in dollars." }, "total_debt_payments": { "type": "number", "description": "The client's monthly payments on their other debts now, in dollars." }, "total_monthly_outflow": { "type": "number", "description": "The mortgage and the debt payments together, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years if nothing changes." }, "longest_payoff_years": { "type": "number", "description": "How many years the slowest debt takes to pay off." }, "debt_balance": { "type": "number", "description": "What the client owes on their other debts, in dollars." }, "debt_rate_pct": { "type": "number", "description": "The blended rate on the other debts, as a PERCENT." }, "debt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many other debts the client has." }, "has_negative_amortization_debt": { "type": "boolean", "description": "`true` when a payment on a debt does not cover its interest, so the balance grows." } }, "required": [ "mortgage_payment", "total_debt_payments", "total_monthly_outflow", "total_interest_5yr", "longest_payoff_years", "debt_balance", "debt_rate_pct", "debt_count", "has_negative_amortization_debt" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage" ], "description": "How the debts are paid out: `refinance` into a new mortgage, `heloc` from a home equity line of credit, or `reverse_mortgage`." }, "subject": { "nullable": true, "description": "Which property the option borrows against: `subject` the client's home, `other_property` another property they own, `blanket` several properties together.", "type": "string", "enum": [ "subject", "other_property", "blanket" ] }, "property_id": { "nullable": true, "description": "The other property the option borrows against, when `subject` is `other_property`.", "type": "string" }, "eligible": { "type": "boolean", "description": "`true` when the client qualifies for this option." }, "reason": { "nullable": true, "description": "Why the client does not qualify. Null when `eligible` is `true`.", "type": "string" }, "new_monthly_payment": { "type": "number", "description": "The client's monthly payment with this option, in dollars." }, "monthly_savings": { "type": "number", "description": "How much less the client pays each month than now, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years with this option, in dollars." }, "interest_saved_5yr": { "type": "number", "description": "The interest the client saves over five years, in dollars." }, "break_even_months": { "type": "number", "description": "How many months the savings take to pay back the cost of the option." }, "new_ltv_pct": { "type": "number", "description": "The loan-to-value ratio after the option, as a PERCENT. `80` means 80%." }, "new_mortgage_balance": { "nullable": true, "description": "The new mortgage balance, in dollars.", "type": "number" }, "new_mortgage_rate_pct": { "nullable": true, "description": "The rate on the new mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "penalty_cost": { "nullable": true, "description": "The penalty to break the current mortgage, in dollars.", "type": "number" }, "penalty_unknown": { "type": "boolean", "description": "`true` when BrokerPlus does not know the penalty, so the figures leave it out." }, "secured_debt_payout": { "nullable": true, "description": "The secured debts on the property that the option pays out, in dollars.", "type": "number" }, "heloc_draw": { "nullable": true, "description": "How much the client draws on the line of credit, in dollars.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The rate on the line of credit, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_interest_only_payment": { "nullable": true, "description": "The monthly interest-only payment on the line of credit, in dollars.", "type": "number" }, "heloc_principal_and_interest_payment": { "nullable": true, "description": "The monthly payment that also pays down the line of credit, in dollars.", "type": "number" }, "equity_at_5yr": { "nullable": true, "description": "The client's equity after five years, in dollars.", "type": "number" }, "equity_at_10yr": { "nullable": true, "description": "The client's equity after ten years, in dollars.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The rate on the reverse mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "requires_rental_qualification": { "type": "boolean", "description": "`true` when the lender must qualify the client on the rental income of the property." } }, "required": [ "type", "subject", "property_id", "eligible", "reason", "new_monthly_payment", "monthly_savings", "total_interest_5yr", "interest_saved_5yr", "break_even_months", "new_ltv_pct", "new_mortgage_balance", "new_mortgage_rate_pct", "penalty_cost", "penalty_unknown", "secured_debt_payout", "heloc_draw", "heloc_rate_pct", "heloc_interest_only_payment", "heloc_principal_and_interest_payment", "equity_at_5yr", "equity_at_10yr", "reverse_mortgage_rate_pct", "requires_rental_qualification" ], "additionalProperties": false }, "description": "Every option BrokerPlus compared." }, "default_rates": { "type": "object", "properties": { "refinance_rate_pct": { "nullable": true, "description": "The refinance rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "refinance_rate_pct", "heloc_rate_pct" ], "additionalProperties": false, "description": "The rates the analysis uses by default." }, "inputs": { "nullable": true, "description": "The figures the analysis read from the deal and the rates it used.", "type": "object", "properties": { "mortgage_balance": { "type": "number", "description": "The balance on the current mortgage, in dollars." }, "mortgage_rate_pct": { "type": "number", "description": "The rate on the current mortgage, as a PERCENT." }, "mortgage_payment": { "type": "number", "description": "The monthly payment on the current mortgage, in dollars." }, "property_value": { "type": "number", "description": "The value of the client's home, in dollars." }, "remaining_term_months": { "type": "number", "description": "The months left in the current mortgage term." }, "amortization_months": { "type": "number", "description": "The amortization used for the new mortgage, in months." }, "penalty": { "type": "number", "description": "The penalty to break the current mortgage, in dollars." }, "new_mortgage_rate_pct": { "nullable": true, "description": "The refinance rate the analysis used, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The reverse mortgage rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "rental_heloc_rate_pct": { "nullable": true, "description": "The rental line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "mortgage_balance", "mortgage_rate_pct", "mortgage_payment", "property_value", "remaining_term_months", "amortization_months", "penalty", "new_mortgage_rate_pct", "heloc_rate_pct", "reverse_mortgage_rate_pct", "rental_heloc_rate_pct" ], "additionalProperties": false }, "created_at": { "type": "string", "description": "When the analysis ran. An analysis never changes: run a new one to update it." } }, "required": [ "object", "id", "deal_id", "recommendation", "recommendation_tier", "recommendation_text", "monthly_savings", "recommended_option_index", "status_quo", "options", "default_rates", "inputs", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The deal has no debt with a `debt_type` (NO_DEBTS), or no property value (NO_PROPERTY_VALUE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/consolidation-analyses/{analysisId}": { "get": { "operationId": "getDealConsolidationAnalysis", "summary": "Retrieve a debt consolidation analysis", "description": "One debt consolidation analysis: the client's position now, each option BrokerPlus compared, and the one it recommends. Every rate is a PERCENT.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "analysisId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "consolidation_analysis", "description": "The type of this record. Always `consolidation_analysis`.", "type": "string", "enum": [ "consolidation_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "deal_id": { "type": "string", "description": "The deal that the analysis is for." }, "recommendation": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage", "not_viable", "not_recommended" ], "description": "The option BrokerPlus recommends, or `not_viable` when no option works for the client." }, "recommendation_tier": { "nullable": true, "description": "How strongly BrokerPlus recommends the option. Null on an analysis saved before tiers existed.", "type": "string", "enum": [ "strong", "recommended", "conditional", "unlikely", "not_recommended" ] }, "recommendation_text": { "nullable": true, "description": "The recommendation in words, as the broker sees it.", "type": "string" }, "monthly_savings": { "nullable": true, "description": "How much less the client pays each month with the recommended option, in dollars.", "type": "number" }, "recommended_option_index": { "nullable": true, "description": "The position of the recommended option in `options`, from 0. Null when no option is recommended.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status_quo": { "nullable": true, "description": "The client's position if nothing changes. Null on an incomplete analysis: run it again.", "type": "object", "properties": { "mortgage_payment": { "type": "number", "description": "The client's monthly mortgage payment now, in dollars." }, "total_debt_payments": { "type": "number", "description": "The client's monthly payments on their other debts now, in dollars." }, "total_monthly_outflow": { "type": "number", "description": "The mortgage and the debt payments together, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years if nothing changes." }, "longest_payoff_years": { "type": "number", "description": "How many years the slowest debt takes to pay off." }, "debt_balance": { "type": "number", "description": "What the client owes on their other debts, in dollars." }, "debt_rate_pct": { "type": "number", "description": "The blended rate on the other debts, as a PERCENT." }, "debt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many other debts the client has." }, "has_negative_amortization_debt": { "type": "boolean", "description": "`true` when a payment on a debt does not cover its interest, so the balance grows." } }, "required": [ "mortgage_payment", "total_debt_payments", "total_monthly_outflow", "total_interest_5yr", "longest_payoff_years", "debt_balance", "debt_rate_pct", "debt_count", "has_negative_amortization_debt" ], "additionalProperties": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refinance", "heloc", "reverse_mortgage" ], "description": "How the debts are paid out: `refinance` into a new mortgage, `heloc` from a home equity line of credit, or `reverse_mortgage`." }, "subject": { "nullable": true, "description": "Which property the option borrows against: `subject` the client's home, `other_property` another property they own, `blanket` several properties together.", "type": "string", "enum": [ "subject", "other_property", "blanket" ] }, "property_id": { "nullable": true, "description": "The other property the option borrows against, when `subject` is `other_property`.", "type": "string" }, "eligible": { "type": "boolean", "description": "`true` when the client qualifies for this option." }, "reason": { "nullable": true, "description": "Why the client does not qualify. Null when `eligible` is `true`.", "type": "string" }, "new_monthly_payment": { "type": "number", "description": "The client's monthly payment with this option, in dollars." }, "monthly_savings": { "type": "number", "description": "How much less the client pays each month than now, in dollars." }, "total_interest_5yr": { "type": "number", "description": "The interest the client pays over five years with this option, in dollars." }, "interest_saved_5yr": { "type": "number", "description": "The interest the client saves over five years, in dollars." }, "break_even_months": { "type": "number", "description": "How many months the savings take to pay back the cost of the option." }, "new_ltv_pct": { "type": "number", "description": "The loan-to-value ratio after the option, as a PERCENT. `80` means 80%." }, "new_mortgage_balance": { "nullable": true, "description": "The new mortgage balance, in dollars.", "type": "number" }, "new_mortgage_rate_pct": { "nullable": true, "description": "The rate on the new mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "penalty_cost": { "nullable": true, "description": "The penalty to break the current mortgage, in dollars.", "type": "number" }, "penalty_unknown": { "type": "boolean", "description": "`true` when BrokerPlus does not know the penalty, so the figures leave it out." }, "secured_debt_payout": { "nullable": true, "description": "The secured debts on the property that the option pays out, in dollars.", "type": "number" }, "heloc_draw": { "nullable": true, "description": "How much the client draws on the line of credit, in dollars.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The rate on the line of credit, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_interest_only_payment": { "nullable": true, "description": "The monthly interest-only payment on the line of credit, in dollars.", "type": "number" }, "heloc_principal_and_interest_payment": { "nullable": true, "description": "The monthly payment that also pays down the line of credit, in dollars.", "type": "number" }, "equity_at_5yr": { "nullable": true, "description": "The client's equity after five years, in dollars.", "type": "number" }, "equity_at_10yr": { "nullable": true, "description": "The client's equity after ten years, in dollars.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The rate on the reverse mortgage, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "requires_rental_qualification": { "type": "boolean", "description": "`true` when the lender must qualify the client on the rental income of the property." } }, "required": [ "type", "subject", "property_id", "eligible", "reason", "new_monthly_payment", "monthly_savings", "total_interest_5yr", "interest_saved_5yr", "break_even_months", "new_ltv_pct", "new_mortgage_balance", "new_mortgage_rate_pct", "penalty_cost", "penalty_unknown", "secured_debt_payout", "heloc_draw", "heloc_rate_pct", "heloc_interest_only_payment", "heloc_principal_and_interest_payment", "equity_at_5yr", "equity_at_10yr", "reverse_mortgage_rate_pct", "requires_rental_qualification" ], "additionalProperties": false }, "description": "Every option BrokerPlus compared." }, "default_rates": { "type": "object", "properties": { "refinance_rate_pct": { "nullable": true, "description": "The refinance rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate BrokerPlus uses when you send none, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "refinance_rate_pct", "heloc_rate_pct" ], "additionalProperties": false, "description": "The rates the analysis uses by default." }, "inputs": { "nullable": true, "description": "The figures the analysis read from the deal and the rates it used.", "type": "object", "properties": { "mortgage_balance": { "type": "number", "description": "The balance on the current mortgage, in dollars." }, "mortgage_rate_pct": { "type": "number", "description": "The rate on the current mortgage, as a PERCENT." }, "mortgage_payment": { "type": "number", "description": "The monthly payment on the current mortgage, in dollars." }, "property_value": { "type": "number", "description": "The value of the client's home, in dollars." }, "remaining_term_months": { "type": "number", "description": "The months left in the current mortgage term." }, "amortization_months": { "type": "number", "description": "The amortization used for the new mortgage, in months." }, "penalty": { "type": "number", "description": "The penalty to break the current mortgage, in dollars." }, "new_mortgage_rate_pct": { "nullable": true, "description": "The refinance rate the analysis used, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "heloc_rate_pct": { "nullable": true, "description": "The line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "reverse_mortgage_rate_pct": { "nullable": true, "description": "The reverse mortgage rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" }, "rental_heloc_rate_pct": { "nullable": true, "description": "The rental line of credit rate the analysis used, when you set one, as a PERCENT. `5.49` means 5.49%.", "type": "number" } }, "required": [ "mortgage_balance", "mortgage_rate_pct", "mortgage_payment", "property_value", "remaining_term_months", "amortization_months", "penalty", "new_mortgage_rate_pct", "heloc_rate_pct", "reverse_mortgage_rate_pct", "rental_heloc_rate_pct" ], "additionalProperties": false }, "created_at": { "type": "string", "description": "When the analysis ran. An analysis never changes: run a new one to update it." } }, "required": [ "object", "id", "deal_id", "recommendation", "recommendation_tier", "recommendation_text", "monthly_savings", "recommended_option_index", "status_quo", "options", "default_rates", "inputs", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities": { "get": { "operationId": "listOpportunities", "summary": "List renewal and refinance opportunities", "description": "The book: one opportunity for each mortgage the brokerage tracks, with its balance, its penalty to break, and what the client saves by moving. Every rate is a percent (`4.99` means 4.99%). Pass `deal_id` to get the one opportunity for a deal. A dismissed opportunity is in the list, with `dismissed_at` set; send `dismissed=false` to leave it out. The filters match the filters on the book in BrokerPlus, and you can combine them. A list filter takes values separated by commas, and an unknown value gets `400 VALIDATION_ERROR` with the accepted values.", "tags": [ "Opportunities" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Returns only the opportunity for this deal. A deal has at most one." }, { "name": "monthly_reports_enabled", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns only the clients enrolled in recurring equity reports, paused or not. `false` returns the rest." }, { "name": "dismissed", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns only the opportunities the broker took off the book (`dismissed_at` is set). `false` returns only the ones still on it." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns only the mortgages whose term has ended, so that BrokerPlus archived the deal. `false` returns only the live ones, as the book shows by default." }, { "name": "maturity_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Returns only the mortgages that mature on or after this day, as `YYYY-MM-DD`. The maturity date is the one on the deal's application, or the deal's own when the application has none. A mortgage with no maturity date is left out." }, { "name": "maturity_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Returns only the mortgages that mature on or before this day, as `YYYY-MM-DD`. Use it with `maturity_from` for a renewal window, for example `maturity_from=2027-01-01&maturity_to=2027-03-31`." }, { "name": "opportunity_type", "in": "query", "required": false, "schema": { "type": "string", "example": "renewal,pre_renewal" }, "description": "Returns only these kinds of opportunity, separated by commas: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. This is the deal's `opportunity_type`." }, { "name": "product_type", "in": "query", "required": false, "schema": { "type": "string", "example": "variable,arm" }, "description": "Returns only these rate types, separated by commas: `fixed`, `variable`, `arm` (adjustable rate), or `heloc` (a secured line of credit). The rate type comes from the deal's application. A mortgage with no rate type matches none of them." }, { "name": "start_year", "in": "query", "required": false, "schema": { "type": "string", "example": "2021,2022" }, "description": "Returns only the mortgages that started in one of these years, separated by commas, for example `2021,2022`. It reads `start_date`." }, { "name": "assigned_broker_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Returns only the mortgages on deals assigned to this broker. This is the deal's `assigned_broker_id`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "updated_desc", "maturity_asc", "maturity_desc", "last_client_contact_desc", "last_client_contact_asc" ] }, "description": "The order of the list. `updated_desc` (the default) is the most recently changed first. `maturity_asc` is the soonest maturity first, and `maturity_desc` the latest first. `last_client_contact_desc` is the client who wrote most recently first, and `last_client_contact_asc` the reverse. A mortgage with no date sorts last. You can't use `sort` with `updated_since`, because a sync reads in `updated_at` order." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createOpportunity", "summary": "Add a mortgage to the book", "description": "Adds a mortgage that BrokerPlus tracks but did not place, the same as Add Client on the book. BrokerPlus links the client by `email`, or creates the contact. It creates a deal for the mortgage and returns the new opportunity. `interest_rate` is a PERCENT (`5.25` means 5.25%). Nothing is sent to the client. Each call creates an opportunity, so send `Idempotency-Key` to make a retry safe.", "tags": [ "Opportunities" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The client's first name. Required." }, "last_name": { "description": "The client's last name.", "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The client's email. Required. BrokerPlus links the opportunity to the contact with this email, or creates one." }, "address": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The property's street address, e.g. `12 Main St`. Required." }, "city": { "description": "The property's city.", "type": "string", "maxLength": 100 }, "province": { "description": "The property's province, as a two-letter code, e.g. `ON`.", "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "description": "The property's postal code.", "type": "string", "maxLength": 10 }, "mortgage_amount": { "type": "number", "minimum": 0, "description": "The original mortgage amount, in dollars. Required." }, "balance": { "description": "The balance owing today, in dollars. Omit it to let BrokerPlus estimate it from the original amount and `term_months`.", "type": "number", "minimum": 0 }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Required." }, "maturity_date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "When the term ends, as `YYYY-MM-DD`. Required." }, "term_months": { "description": "The length of the term, in months. Without it, BrokerPlus does not estimate the balance: it uses `balance`, or `mortgage_amount` when you do not send `balance`.", "type": "integer", "minimum": 1, "maximum": 600 }, "amortization_months": { "description": "The amortization, in months.", "type": "integer", "minimum": 0, "maximum": 600 }, "product_type": { "description": "`fixed`, `variable`, or `arm` (adjustable). The default is `fixed`.", "type": "string", "enum": [ "fixed", "variable", "arm" ] }, "lender": { "description": "The lender, as brokers name it.", "type": "string", "maxLength": 120 }, "property_value": { "description": "What the property is worth, in dollars. Omit it to let BrokerPlus estimate it.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "board_id": { "description": "The pipeline the deal lands on. Omit it to use the default.", "type": "string" }, "stage_id": { "description": "The stage within `board_id`. Omit it to use the first stage.", "type": "string" } }, "required": [ "first_name", "email", "address", "mortgage_amount", "interest_rate", "maturity_date" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A required field is missing (VALIDATION_ERROR or INVALID_INPUT), or `board_id` or `stage_id` is not a pipeline of your team (INVALID_BOARD or INVALID_BOARD_STAGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}": { "get": { "operationId": "getOpportunity", "summary": "Retrieve an opportunity", "description": "One opportunity. Use `deal_id` to read the deal it belongs to.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateOpportunity", "summary": "Update what a tracked mortgage carries", "description": "Corrects the figures that come off a lender statement: the balance, the rate, the payment, the property value and the payout penalty. Send only the fields to change. `interest_rate` and `prime_adjustment` are PERCENT here (`5.25` means 5.25%). A balance you send is paid down from today onward, and neither our nightly recalculation nor an import overwrites it; send null to hand it back. The penalties, savings and target rate on the object are recalculated from what you send, so they can all change in one response. `segments` replaces every part of a split mortgage, so send each one to keep.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A title for this mortgage on the book. Clients never see it. Send null or an empty string to follow the deal's name.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "description": "Balance owing, in dollars, as of now. BrokerPlus pays it down from today onward and stops re-deriving it. Send null to hand it back to BrokerPlus.", "nullable": true, "type": "number", "minimum": 0 }, "interest_rate": { "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction. Use this for a fixed rate. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "prime_adjustment": { "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Send null to clear.", "nullable": true, "type": "number", "minimum": -100, "maximum": 100 }, "monthly_payment": { "description": "The payment, in dollars, on a MONTHLY basis, whatever the payment schedule is. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "property_value": { "description": "What the property is worth, in dollars. This replaces our estimate. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "effective_penalty": { "description": "The penalty from the lender's payout statement, in dollars. This replaces the penalty BrokerPlus works out. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "penalty_type": { "description": "Which penalty the lender applies. Send null to let BrokerPlus decide.", "nullable": true, "type": "string", "enum": [ "ird", "three_month" ] }, "comparison_rate": { "description": "The lender's comparison rate for the penalty, as a PERCENT. This replaces the one BrokerPlus works out. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "collateral_charge": { "description": "The amount registered on title, in dollars, for a collateral charge. Send null to clear.", "nullable": true, "type": "number", "minimum": 0 }, "cashback_enabled": { "description": "Count a lender cashback in the savings.", "type": "boolean" }, "cashback_override": { "description": "Your own cashback figure, in dollars. Send null to use the lender's.", "nullable": true, "type": "number", "minimum": 0 }, "property_bedrooms": { "description": "Bedrooms. This replaces our figure. Send null to clear.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 50 }, "property_bathrooms": { "description": "Bathrooms. This replaces our figure. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 50 }, "property_sqft": { "description": "Living area in square feet. This replaces our figure. Send null to clear.", "nullable": true, "type": "number", "minimum": 1, "maximum": 1000000 }, "property_year_built": { "description": "Year built. This replaces our figure. Send null to clear.", "nullable": true, "type": "integer", "minimum": 1800, "maximum": 9007199254740991 }, "property_type": { "description": "The kind of home, e.g. `Condo`. This replaces our figure. Send null to clear.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 60 }, "segments": { "description": "The parts of a split mortgage, in order. Replaces every segment, so send each one to keep. At least one must not be a `heloc`. Send `[]` to make it one loan again. The first segment that is not a `heloc` sets the product, rate and term of the opportunity, and the balances add up to its original amount.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "heloc" ], "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "balance": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "The balance of the segment, in dollars." }, "interest_rate": { "description": "The rate the segment carries. Required unless the segment is a `heloc`, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "exclusiveMaximum": true }, "prime_adjustment": { "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%.", "nullable": true, "type": "number", "minimum": -100, "maximum": 100 }, "term_months": { "description": "The length of the term, in months.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "remaining_term_months": { "description": "The months left in the term.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "maturity_date": { "description": "When the term ends, as `YYYY-MM-DD`.", "nullable": true, "type": "string" }, "start_date": { "description": "When the segment started, as `YYYY-MM-DD`.", "nullable": true, "type": "string" }, "lender": { "description": "The lender that holds the segment.", "nullable": true, "type": "string", "maxLength": 120 }, "label": { "description": "Your name for the segment, e.g. `Portion 2`.", "nullable": true, "type": "string", "maxLength": 120 } }, "required": [ "product_type", "balance" ], "additionalProperties": false } } }, "additionalProperties": false, "description": "Send only the figures you are changing. Anything you leave out stays as it is." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A segment is not valid, or every segment is a `heloc` (INVALID_SEGMENTS, INVALID_SEGMENT_RATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is in a stage that locks it and you sent more than `name` and the rate assumptions (`comparison_rate`, `effective_penalty`, `penalty_type`, `cashback_enabled`, `cashback_override`) (DEAL_LOCKED), or the broker locked the client's details (CLIENT_DATA_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}/convert": { "post": { "operationId": "convertOpportunity", "summary": "Start a deal from an opportunity", "description": "Creates a new working deal from a tracked mortgage, the same as New Deal on the opportunity in BrokerPlus. The deal gets the borrowers and the mortgage facts. The opportunity stays on the book. Returns the new deal. Each call creates a deal, so send `Idempotency-Key` to make a retry safe.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Deal type. Omit it to use the type that matches the opportunity, a refinance or a renewal.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "board_id": { "description": "Pipeline to land on. Omit it to use the broker's default pipeline for the type.", "type": "string" }, "stage_id": { "description": "Stage within `board_id`. Omit it to land on the first stage of the pipeline.", "type": "string" } }, "additionalProperties": false, "description": "Where the new deal lands. Send an empty object to use the defaults." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal", "description": "The type of this record. Always `deal`.", "type": "string", "enum": [ "deal" ] }, "id": { "type": "string", "description": "Stable identifier for the deal." }, "reference_number": { "type": "string", "description": "The human-facing deal number brokers quote, e.g. `D2503-0001`." }, "name": { "nullable": true, "description": "The name a broker gave the deal. Null when the deal uses the brokerage's naming pattern.", "type": "string" }, "type": { "nullable": true, "description": "Deal type, e.g. a purchase, refinance or renewal. Null until the broker sets a type. A deal made from a lead starts with no type.", "type": "string" }, "status": { "type": "string", "description": "Lifecycle status. One of: active, submitted, approved, funded, closed, dead, declined, cancelled, expired, withdrawn, unknown." }, "board_id": { "type": "string", "description": "The pipeline board this deal sits on." }, "board_name": { "nullable": true, "description": "Display name of that board, so you need not resolve the id.", "type": "string" }, "stage_id": { "nullable": true, "description": "Current stage within the board.", "type": "string" }, "stage_name": { "nullable": true, "description": "Display name of that stage, so you need not resolve the id.", "type": "string" }, "assigned_broker_id": { "nullable": true, "description": "The broker responsible. Null if unassigned.", "type": "string" }, "assigned_broker_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "closing_at": { "nullable": true, "description": "Scheduled closing date, once one is set.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the deal funded. Null until it does.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it was submitted to a lender.", "type": "string" }, "maturity_date": { "nullable": true, "description": "Mortgage maturity, for renewal targeting.", "type": "string" }, "underwriter_id": { "nullable": true, "description": "The user who underwrites the deal. Null if nobody does.", "type": "string" }, "underwriter_name": { "nullable": true, "description": "The underwriter's name. Null if nobody underwrites the deal.", "type": "string" }, "lender_id": { "nullable": true, "description": "The lender the deal is placed with. Resolve against `GET /lenders`. Null until the broker picks one.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name. Null until the broker picks a lender.", "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Resolve against `GET /contacts/{id}`." }, "role": { "type": "string", "description": "Their part in the deal, e.g. borrower or guarantor." }, "role_label": { "nullable": true, "description": "The brokerage's own word for this person's seat on the deal, e.g. `Listing Realtor`. Null when the role alone names it.", "type": "string" } }, "required": [ "contact_id", "role", "role_label" ], "additionalProperties": false }, "description": "Everyone attached to the deal. Ids only - fetch the contact for details." }, "lender_file_ref": { "nullable": true, "description": "The lender's own file number for this deal, when the broker recorded it.", "type": "string" }, "referral_partner": { "nullable": true, "description": "Who referred this deal. Null when nobody did. Set it with `POST /deals/{id}/referral-partner`.", "type": "object", "properties": { "id": { "type": "string", "description": "The partner. Read their history with `GET /referral-partners/{id}`." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name, for display." }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" } }, "required": [ "id", "contact_id", "name", "type" ], "additionalProperties": false }, "external_references": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The system that holds the record: `velocity_forms`, `finmo`, or `velocity` for a loan code from an import." }, "reference": { "type": "string", "description": "The record's id in that system, verbatim." }, "is_active": { "type": "boolean", "description": "False when the link was cut. The reference is kept so it is never matched as new." }, "url": { "nullable": true, "description": "Where the record opens in that system. Null when the system gave no link, and on a `velocity` loan code.", "type": "string" }, "remote_status": { "nullable": true, "description": "The other system's own status for the record, word for word, e.g. `review`. It is not the deal's `status`. Null until that system reports one.", "type": "string" }, "remote_status_at": { "nullable": true, "description": "When the other system last reported `remote_status`.", "type": "string" }, "last_pulled_at": { "nullable": true, "description": "When BrokerPlus last read the record's details from that system. Null if it never has.", "type": "string" }, "created_at": { "nullable": true, "description": "When the deal was linked to the record. Null on a `velocity` loan code.", "type": "string" } }, "required": [ "source", "reference", "is_active", "url", "remote_status", "remote_status_at", "last_pulled_at", "created_at" ], "additionalProperties": false }, "description": "The deal's ids in other systems. Match an old record on these with `GET /deals?external_reference=`." }, "stage_entered_at": { "nullable": true, "description": "When the deal moved into its current stage.", "type": "string" }, "application_date": { "nullable": true, "description": "The date the client applied, as the broker recorded it.", "type": "string" }, "archived_at": { "nullable": true, "description": "When a broker archived the deal. Null while it is not archived.", "type": "string" }, "opportunity_type": { "nullable": true, "description": "For a mortgage on the broker's book, what it is a candidate for: `renewal`, `pre_renewal`, `ird` (a refinance worth breaking the term for), or `both`. Null on an ordinary pipeline deal.", "type": "string" }, "origin": { "type": "string", "description": "Where the deal was first created: `brokerplus`, `velocity`, `finmo`, or `imported` for a file import. It does not change after the deal is edited here." }, "spawned_from_deal_id": { "nullable": true, "description": "The funded deal this renewal or refinance was opened from. Null when it was not opened from one.", "type": "string" }, "realtor_contact_id": { "nullable": true, "description": "The realtor contact named on the client's equity reports. Resolve against `GET /contacts/{id}`. Null when none is set.", "type": "string" }, "primary_application_id": { "nullable": true, "description": "Of the deal's applications, the one that goes to the lender. Null when the deal has no application.", "type": "string" }, "submitting_broker_id": { "nullable": true, "description": "The broker whose licence the file goes to the lender under, when it is not the assigned broker. Null when nobody was named.", "type": "string" }, "channel_id": { "nullable": true, "description": "The acquisition channel the business came through, carried over from the lead. Resolve against `GET /lead-channels`. Null when none is set.", "type": "string" }, "created_at": { "type": "string", "description": "When the deal was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "reference_number", "name", "type", "status", "board_id", "board_name", "stage_id", "stage_name", "assigned_broker_id", "assigned_broker_name", "closing_at", "funded_at", "submitted_at", "maturity_date", "underwriter_id", "underwriter_name", "lender_id", "lender_name", "contacts", "lender_file_ref", "referral_partner", "external_references", "stage_entered_at", "application_date", "archived_at", "opportunity_type", "origin", "spawned_from_deal_id", "realtor_contact_id", "primary_application_id", "submitting_broker_id", "channel_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The opportunity is a lead with no mortgage yet (LEAD_MODE_CANDIDATE), or the placement is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}/dismiss": { "post": { "operationId": "dismissOpportunity", "summary": "Take an opportunity off the book", "description": "Stops the outreach for this mortgage, the same as Dismiss in BrokerPlus. Equity reports and renewal signals for it stop. Nothing is deleted. A second call changes nothing. Undo it with `POST /opportunities/{id}/restore`.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is in a stage that locks it (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}/restore": { "post": { "operationId": "restoreOpportunity", "summary": "Put a dismissed opportunity back on the book", "description": "Undoes a dismiss. The outreach continues from where it stopped. A second call changes nothing.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is in a stage that locks it (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}/snooze": { "post": { "operationId": "snoozeOpportunity", "summary": "Snooze an opportunity", "description": "Hides the opportunity until a date and reminds the broker that morning, the same as Snooze in BrokerPlus. A new date replaces the old one.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "until": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The day to remind the broker, as `YYYY-MM-DD`. It must be in the future. BrokerPlus reminds the broker that morning in the brokerage time zone." } }, "required": [ "until" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`until` is not a future date (VALIDATION_ERROR or BAD_REQUEST).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is in a stage that locks it (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/opportunities/{id}/unsnooze": { "post": { "operationId": "unsnoozeOpportunity", "summary": "End a snooze", "description": "Clears `snoozed_until` and cancels the reminder. A call on an opportunity with no snooze changes nothing.", "tags": [ "Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "opportunity", "description": "The type of this record. Always `opportunity`.", "type": "string", "enum": [ "opportunity" ] }, "id": { "type": "string", "description": "Stable identifier for the opportunity." }, "deal_id": { "type": "string", "description": "Deal this opportunity belongs to." }, "balance": { "nullable": true, "description": "Last known mortgage balance, in dollars.", "type": "number" }, "balance_as_of": { "nullable": true, "description": "When the balance was captured, as an ISO 8601 timestamp.", "type": "string" }, "balance_is_manual": { "type": "boolean", "description": "True when a person set the balance. BrokerPlus then pays it down from that date instead of re-deriving it." }, "interest_rate": { "nullable": true, "description": "The rate the mortgage carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable rate, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed rate.", "type": "number" }, "original_mortgage_amount": { "nullable": true, "description": "Original principal, in dollars.", "type": "number" }, "start_date": { "nullable": true, "description": "When the mortgage started, as `YYYY-MM-DD`.", "type": "string" }, "monthly_payment": { "nullable": true, "description": "Scheduled monthly payment, in dollars.", "type": "number" }, "ird_penalty": { "nullable": true, "description": "Interest rate differential penalty, in dollars.", "type": "number" }, "three_month_penalty": { "nullable": true, "description": "Three months' interest penalty, in dollars.", "type": "number" }, "effective_penalty": { "nullable": true, "description": "The penalty that applies: the greater of the two above, unless the broker set one.", "type": "number" }, "penalty_type": { "nullable": true, "description": "Which penalty the lender applies, when somebody has said. Null when BrokerPlus decides.", "type": "string", "enum": [ "ird", "three_month" ] }, "renewal_savings": { "nullable": true, "description": "Savings if the client switches at maturity, in dollars.", "type": "number" }, "target_new_rate": { "nullable": true, "description": "Best rate we can find for this client, as a PERCENT, e.g. `4.99` means 4.99%.", "type": "number" }, "breakeven_rate": { "nullable": true, "description": "Rate at which net savings reach zero, as a PERCENT. `null` when a switch never pays for itself.", "type": "number" }, "property_value": { "nullable": true, "description": "Current property value, in dollars. The broker's override when they set one, otherwise our estimate.", "type": "number" }, "property_value_source": { "nullable": true, "description": "Where the estimate came from.", "type": "string" }, "property_assessment": { "nullable": true, "description": "Assessed value, in dollars.", "type": "number" }, "equity_opportunity": { "type": "boolean", "description": "`true` when the client has equity worth a conversation." }, "monthly_reports_enabled": { "type": "boolean", "description": "`true` when the client receives an automatic equity report." }, "outreach_unsubscribed_at": { "nullable": true, "description": "When the client opted out of equity reports. Other communication remains permitted.", "type": "string" }, "snoozed_until": { "nullable": true, "description": "When the broker asked to be reminded again. Set it with `POST /opportunities/{id}/snooze`.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the broker took this mortgage off the book. Null while it is on the book. A dismissed opportunity gets no outreach. Undo it with `POST /opportunities/{id}/restore`.", "type": "string" }, "last_contacted_at": { "nullable": true, "description": "When the broker last contacted the client.", "type": "string" }, "name": { "nullable": true, "description": "A title the broker gave this mortgage on the book. Null follows the deal's name.", "type": "string" }, "comparison_rate": { "nullable": true, "description": "The rate the lender compares against to work out an interest rate differential penalty, as a PERCENT. The broker's own figure when they entered one, else the one BrokerPlus works out. Null when there is none.", "type": "number" }, "collateral_charge": { "nullable": true, "description": "For a collateral charge mortgage, the amount registered on title, in dollars. It is often more than the balance. Null on a standard charge.", "type": "number" }, "cashback_enabled": { "type": "boolean", "description": "`true` when the broker counts a lender cashback in the savings." }, "cashback_override": { "nullable": true, "description": "The cashback the broker typed, in dollars. Null uses the lender's own cashback.", "type": "number" }, "best_option_pin": { "nullable": true, "description": "The renewal or switch option the broker chose to show the client, in place of the best one BrokerPlus picks. Null when the broker has not chosen one.", "type": "object", "properties": { "lender_slug": { "nullable": true, "description": "The lender the broker picked.", "type": "string" }, "term_months": { "nullable": true, "description": "The term the broker picked, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product_type": { "nullable": true, "description": "`fixed`, `variable`, `arm`, `prime` or `rental`.", "type": "string" }, "rate": { "nullable": true, "description": "The rate the broker typed for it, as a PERCENT. Null uses the lender's rate.", "type": "number" } }, "required": [ "lender_slug", "term_months", "product_type", "rate" ], "additionalProperties": false }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who took this mortgage off the book.", "type": "string" }, "last_client_contact_at": { "nullable": true, "description": "When the client last emailed the broker.", "type": "string" }, "client_perceived_value": { "nullable": true, "description": "What the client said their home is worth, in dollars, from an equity report. It does not change `property_value`.", "type": "number" }, "client_perceived_value_at": { "nullable": true, "description": "When the client gave `client_perceived_value`.", "type": "string" }, "property_bedrooms": { "nullable": true, "description": "Bedrooms. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_bathrooms": { "nullable": true, "description": "Bathrooms, with `0.5` for a half bath. The broker's figure when they entered one.", "type": "number" }, "property_sqft": { "nullable": true, "description": "Living area in square feet. The broker's figure when they entered one.", "type": "number" }, "property_year_built": { "nullable": true, "description": "Year built. The broker's figure when they entered one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "property_type": { "nullable": true, "description": "The kind of home, e.g. `Condo`, in the source's own words. The broker's when they entered one.", "type": "string" }, "last_equity_report_sent_at": { "nullable": true, "description": "When the client was last sent an equity report.", "type": "string" }, "monthly_reports_enabled_at": { "nullable": true, "description": "When the client was signed up for automatic reports.", "type": "string" }, "monthly_reports_paused_at": { "nullable": true, "description": "When the broker paused the client's reports. Null while they are not paused.", "type": "string" }, "reports_proposed_at": { "nullable": true, "description": "When a lead form asked for this client to get reports. Null when none did, or once the broker answered.", "type": "string" }, "reports_proposal_declined_at": { "nullable": true, "description": "When the broker said no to that request.", "type": "string" }, "outreach_blocked_at": { "nullable": true, "description": "When outreach was held because the client never agreed to it, as on an imported file. Null once the broker turns it on.", "type": "string" }, "report_frequency": { "type": "string", "description": "How often the client's equity report goes out: `monthly`, `quarterly`, `semi_annually` or `annually`." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_segment", "description": "The type of this record. Always `mortgage_segment`.", "type": "string", "enum": [ "mortgage_segment" ] }, "id": { "type": "string", "description": "Stable identifier for the segment. A new one is issued each time the segments are replaced." }, "product_type": { "type": "string", "description": "What the segment is: `fixed`, `variable`, `arm` (adjustable rate) or `heloc` (line of credit)." }, "lender": { "nullable": true, "description": "The lender that holds the segment. Null if not recorded.", "type": "string" }, "balance": { "type": "number", "description": "The balance of the segment, in dollars." }, "interest_rate": { "nullable": true, "description": "The rate the segment carries, as a PERCENT, e.g. `5.25` means 5.25%. Not a fraction.", "type": "number" }, "prime_adjustment": { "nullable": true, "description": "For a variable segment, the distance from prime, as a PERCENT. `-0.5` means prime minus 0.50%. Null on a fixed one.", "type": "number" }, "term_months": { "nullable": true, "description": "The length of the term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_term_months": { "nullable": true, "description": "The months left in the term when it was entered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maturity_date": { "nullable": true, "description": "When the term ends, as `YYYY-MM-DD`.", "type": "string" }, "start_date": { "nullable": true, "description": "When the segment started, as `YYYY-MM-DD`.", "type": "string" }, "label": { "nullable": true, "description": "The broker's name for the segment, e.g. `Portion 2`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the segment sits in the list, from 0." } }, "required": [ "object", "id", "product_type", "lender", "balance", "interest_rate", "prime_adjustment", "term_months", "remaining_term_months", "amortization_months", "maturity_date", "start_date", "label", "position" ], "additionalProperties": false }, "description": "The parts of a split mortgage, in order, for example a fixed portion beside a line of credit. Empty when the mortgage is one loan." }, "created_at": { "type": "string", "description": "When the opportunity was created, as an ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "When the opportunity last changed, as an ISO 8601 timestamp." } }, "required": [ "object", "id", "deal_id", "balance", "balance_as_of", "balance_is_manual", "interest_rate", "prime_adjustment", "original_mortgage_amount", "start_date", "monthly_payment", "ird_penalty", "three_month_penalty", "effective_penalty", "penalty_type", "renewal_savings", "target_new_rate", "breakeven_rate", "property_value", "property_value_source", "property_assessment", "equity_opportunity", "monthly_reports_enabled", "outreach_unsubscribed_at", "snoozed_until", "dismissed_at", "last_contacted_at", "name", "comparison_rate", "collateral_charge", "cashback_enabled", "cashback_override", "best_option_pin", "dismissed_by_user_id", "last_client_contact_at", "client_perceived_value", "client_perceived_value_at", "property_bedrooms", "property_bathrooms", "property_sqft", "property_year_built", "property_type", "last_equity_report_sent_at", "monthly_reports_enabled_at", "monthly_reports_paused_at", "reports_proposed_at", "reports_proposal_declined_at", "outreach_blocked_at", "report_frequency", "segments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal is in a stage that locks it (DEAL_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/organization": { "get": { "operationId": "getOrganization", "summary": "Retrieve your brokerage", "description": "The brokerage the key belongs to, with its brand colors and logo.", "tags": [ "Identity" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "organization", "description": "The type of this record. Always `organization`.", "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "description": "Stable identifier for the brokerage." }, "name": { "type": "string", "description": "Brokerage name." }, "slug": { "type": "string", "description": "Machine-readable name, unique across BrokerPlus." }, "primary_color": { "type": "string", "description": "Resolved brand primary, as a hex string. Falls back to the BrokerPlus default when unset." }, "secondary_color": { "type": "string", "description": "Resolved brand secondary, as a hex string. Falls back to the BrokerPlus default when unset." }, "logo_url": { "nullable": true, "description": "The brokerage's own logo. Null when they have not set one.", "type": "string" }, "has_book_of_business": { "type": "boolean", "description": "True when the brokerage uses the book of business: funded mortgages it follows for renewals, refinances and equity reports." }, "created_at": { "type": "string", "description": "When the brokerage was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "slug", "primary_color", "secondary_color", "logo_url", "has_book_of_business", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/direct-threads": { "get": { "operationId": "listDirectThreads", "summary": "List team chat conversations", "description": "The team chat conversations that the broker your key acts as is in: two-person conversations and groups, the newest message first. A conversation the broker is not in is never listed.", "tags": [ "Teams" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "direct_thread", "description": "The type of this record. Always `direct_thread`.", "type": "string", "enum": [ "direct_thread" ] }, "id": { "type": "string", "description": "Stable identifier for the conversation." }, "group": { "type": "boolean", "description": "`true` for a group, `false` for a conversation between two people. A group has a `title`." }, "title": { "nullable": true, "description": "The name of a group. Null for a conversation between two people.", "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The member's user." }, "name": { "nullable": true, "description": "The member's name, for display.", "type": "string" }, "email": { "type": "string", "description": "The member's email address." }, "last_read_at": { "nullable": true, "description": "When the member last read the conversation. Null if they have not opened it yet.", "type": "string" } }, "required": [ "user_id", "name", "email", "last_read_at" ], "additionalProperties": false }, "description": "Everybody in the conversation, the broker your key acts as included." }, "last_message_at": { "type": "string", "description": "When the newest message was sent. For a new conversation, when it started." }, "last_message_preview": { "nullable": true, "description": "The start of the newest message, as text. Null if nobody has written yet.", "type": "string" }, "last_message_by_user_id": { "nullable": true, "description": "Who wrote the newest message.", "type": "string" }, "unread": { "type": "boolean", "description": "`true` if a teammate wrote after the broker your key acts as last read the conversation." }, "created_at": { "type": "string", "description": "When the conversation started." }, "updated_at": { "type": "string", "description": "When the conversation last changed." } }, "required": [ "object", "id", "group", "title", "members", "last_message_at", "last_message_preview", "last_message_by_user_id", "unread", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDirectThread", "summary": "Start a team chat conversation", "description": "With one teammate in `user_ids`, opens the conversation with them. If the broker already has one, you get that conversation. With two or more, or with a `title`, starts a new group. Each teammate must be in `GET /v1/direct-threads/roster`.", "tags": [ "Teams" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The teammates to talk to. One teammate opens your conversation with them, or returns the one you already have. Two or more start a new group. Get them from `GET /v1/direct-threads/roster`." }, "title": { "description": "The name of a group, at most 80 characters. A title always starts a group.", "type": "string", "maxLength": 80 } }, "required": [ "user_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "direct_thread", "description": "The type of this record. Always `direct_thread`.", "type": "string", "enum": [ "direct_thread" ] }, "id": { "type": "string", "description": "Stable identifier for the conversation." }, "group": { "type": "boolean", "description": "`true` for a group, `false` for a conversation between two people. A group has a `title`." }, "title": { "nullable": true, "description": "The name of a group. Null for a conversation between two people.", "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The member's user." }, "name": { "nullable": true, "description": "The member's name, for display.", "type": "string" }, "email": { "type": "string", "description": "The member's email address." }, "last_read_at": { "nullable": true, "description": "When the member last read the conversation. Null if they have not opened it yet.", "type": "string" } }, "required": [ "user_id", "name", "email", "last_read_at" ], "additionalProperties": false }, "description": "Everybody in the conversation, the broker your key acts as included." }, "last_message_at": { "type": "string", "description": "When the newest message was sent. For a new conversation, when it started." }, "last_message_preview": { "nullable": true, "description": "The start of the newest message, as text. Null if nobody has written yet.", "type": "string" }, "last_message_by_user_id": { "nullable": true, "description": "Who wrote the newest message.", "type": "string" }, "unread": { "type": "boolean", "description": "`true` if a teammate wrote after the broker your key acts as last read the conversation." }, "created_at": { "type": "string", "description": "When the conversation started." }, "updated_at": { "type": "string", "description": "When the conversation last changed." } }, "required": [ "object", "id", "group", "title", "members", "last_message_at", "last_message_preview", "last_message_by_user_id", "unread", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A group has fewer than two other people, or `user_ids` names only the broker (BAD_REQUEST).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "A teammate is not one the broker can message (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/direct-threads/roster": { "get": { "operationId": "listDirectThreadRoster", "summary": "List the teammates you can message", "description": "The people the broker can start a conversation with: the active members of each team the broker is on. It is the same list as the team chat in BrokerPlus. Not paged.", "tags": [ "Teams" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "teammate", "description": "The type of this record. Always `teammate`.", "type": "string", "enum": [ "teammate" ] }, "id": { "type": "string", "description": "The teammate's user." }, "name": { "nullable": true, "description": "The teammate's name, for display.", "type": "string" }, "email": { "type": "string", "description": "The teammate's email address." } }, "required": [ "object", "id", "name", "email" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/direct-threads/{id}": { "get": { "operationId": "getDirectThread", "summary": "Retrieve a team chat conversation", "description": "One conversation, with its members and where each of them has read to.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "direct_thread", "description": "The type of this record. Always `direct_thread`.", "type": "string", "enum": [ "direct_thread" ] }, "id": { "type": "string", "description": "Stable identifier for the conversation." }, "group": { "type": "boolean", "description": "`true` for a group, `false` for a conversation between two people. A group has a `title`." }, "title": { "nullable": true, "description": "The name of a group. Null for a conversation between two people.", "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The member's user." }, "name": { "nullable": true, "description": "The member's name, for display.", "type": "string" }, "email": { "type": "string", "description": "The member's email address." }, "last_read_at": { "nullable": true, "description": "When the member last read the conversation. Null if they have not opened it yet.", "type": "string" } }, "required": [ "user_id", "name", "email", "last_read_at" ], "additionalProperties": false }, "description": "Everybody in the conversation, the broker your key acts as included." }, "last_message_at": { "type": "string", "description": "When the newest message was sent. For a new conversation, when it started." }, "last_message_preview": { "nullable": true, "description": "The start of the newest message, as text. Null if nobody has written yet.", "type": "string" }, "last_message_by_user_id": { "nullable": true, "description": "Who wrote the newest message.", "type": "string" }, "unread": { "type": "boolean", "description": "`true` if a teammate wrote after the broker your key acts as last read the conversation." }, "created_at": { "type": "string", "description": "When the conversation started." }, "updated_at": { "type": "string", "description": "When the conversation last changed." } }, "required": [ "object", "id", "group", "title", "members", "last_message_at", "last_message_preview", "last_message_by_user_id", "unread", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The conversation does not exist, or the broker is not in it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/direct-threads/{id}/messages": { "get": { "operationId": "listDirectMessages", "summary": "List the messages in a conversation", "description": "The messages in a team chat conversation, newest first. Reading them does not mark them read.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "direct_message", "description": "The type of this record. Always `direct_message`.", "type": "string", "enum": [ "direct_message" ] }, "id": { "type": "string", "description": "Stable identifier for the message." }, "thread_id": { "type": "string", "description": "The conversation the message is in." }, "sender_user_id": { "type": "string", "description": "Who wrote the message." }, "body": { "type": "string", "description": "The message as HTML, as BrokerPlus shows it." }, "body_text": { "type": "string", "description": "The message as plain text." }, "created_at": { "type": "string", "description": "When the message was sent." } }, "required": [ "object", "id", "thread_id", "sender_user_id", "body", "body_text", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The conversation does not exist, or the broker is not in it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "sendDirectMessage", "summary": "Send a message to a conversation", "description": "Posts a message from the broker your key acts as. The other members see it in their team chat at once. A team chat message stays inside the brokerage: it never goes to a client. Supports `Idempotency-Key`.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "description": "The message. Plain text or HTML, at most 4000 characters of text. Unsafe HTML is removed. The result must contain visible content." } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "direct_message", "description": "The type of this record. Always `direct_message`.", "type": "string", "enum": [ "direct_message" ] }, "id": { "type": "string", "description": "Stable identifier for the message." }, "thread_id": { "type": "string", "description": "The conversation the message is in." }, "sender_user_id": { "type": "string", "description": "Who wrote the message." }, "body": { "type": "string", "description": "The message as HTML, as BrokerPlus shows it." }, "body_text": { "type": "string", "description": "The message as plain text." }, "created_at": { "type": "string", "description": "When the message was sent." } }, "required": [ "object", "id", "thread_id", "sender_user_id", "body", "body_text", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The conversation does not exist, or the broker is not in it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/direct-threads/{id}/read": { "post": { "operationId": "markDirectThreadRead", "summary": "Mark a conversation read", "description": "Marks every message in the conversation read for the broker your key acts as. The other members see how far the broker has read.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "direct_thread", "description": "The type of this record. Always `direct_thread`.", "type": "string", "enum": [ "direct_thread" ] }, "id": { "type": "string", "description": "Stable identifier for the conversation." }, "group": { "type": "boolean", "description": "`true` for a group, `false` for a conversation between two people. A group has a `title`." }, "title": { "nullable": true, "description": "The name of a group. Null for a conversation between two people.", "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The member's user." }, "name": { "nullable": true, "description": "The member's name, for display.", "type": "string" }, "email": { "type": "string", "description": "The member's email address." }, "last_read_at": { "nullable": true, "description": "When the member last read the conversation. Null if they have not opened it yet.", "type": "string" } }, "required": [ "user_id", "name", "email", "last_read_at" ], "additionalProperties": false }, "description": "Everybody in the conversation, the broker your key acts as included." }, "last_message_at": { "type": "string", "description": "When the newest message was sent. For a new conversation, when it started." }, "last_message_preview": { "nullable": true, "description": "The start of the newest message, as text. Null if nobody has written yet.", "type": "string" }, "last_message_by_user_id": { "nullable": true, "description": "Who wrote the newest message.", "type": "string" }, "unread": { "type": "boolean", "description": "`true` if a teammate wrote after the broker your key acts as last read the conversation." }, "created_at": { "type": "string", "description": "When the conversation started." }, "updated_at": { "type": "string", "description": "When the conversation last changed." } }, "required": [ "object", "id", "group", "title", "members", "last_message_at", "last_message_preview", "last_message_by_user_id", "unread", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The conversation does not exist, or the broker is not in it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/mail-merges": { "get": { "operationId": "listMailMerges", "summary": "List mail merges", "description": "The mail merges sent from the broker's mailbox, newest first, with how many addresses are in each state. A mail merge is one email that each person on a list gets on their own.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mail_merge", "description": "The type of this record. Always `mail_merge`.", "type": "string", "enum": [ "mail_merge" ] }, "id": { "type": "string", "description": "Stable identifier for the mail merge." }, "sender_user_id": { "type": "string", "description": "The broker whose mailbox the merge went out from." }, "subject": { "nullable": true, "description": "The subject of the email. Null if it had none.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When the merge is set to go out. Null if it went out at once.", "type": "string" }, "recipient_counts": { "type": "object", "properties": { "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies waiting to go out." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies the mail provider accepted." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies that could not go out." }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses BrokerPlus did not write to, because the person unsubscribed or withdrew consent." } }, "required": [ "queued", "sent", "failed", "skipped" ], "additionalProperties": false, "description": "How many addresses are in each state. Read each one with `GET /v1/mail-merges/{id}/recipients`." }, "created_at": { "type": "string", "description": "When the merge was sent or scheduled." }, "updated_at": { "type": "string", "description": "When the merge last changed." } }, "required": [ "object", "id", "sender_user_id", "subject", "scheduled_at", "recipient_counts", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createMailMerge", "summary": "Send a mail merge", "description": "Sends one email to each address on the list now, or at `schedule_at`, from the mailbox of the broker your key acts as, the same as Send merge in BrokerPlus. Each person gets their own copy and sees no one else. A person who unsubscribed or withdrew consent is skipped. The response is `201` with the mail merge and a count for each state. Read each address with `GET /v1/mail-merges/{id}/recipients`. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Communications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The address to send one copy to." }, "name": { "description": "The person's name, for a new contact.", "type": "string", "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false }, "description": "The people to email, at most 500 different addresses. Each person gets their own copy and sees no one else. An address that is on the list twice gets one copy. A person who has no contact becomes a new lead." }, "subject": { "description": "The subject of the email.", "type": "string", "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The message, in plain text. Everybody gets the same words, so a merge field such as `{{first_name}}` is refused." }, "schedule_at": { "description": "ISO 8601 date-time to send it at. Leave it out to send it now.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "recipients", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "mail_merge", "description": "The type of this record. Always `mail_merge`.", "type": "string", "enum": [ "mail_merge" ] }, "id": { "type": "string", "description": "Stable identifier for the mail merge." }, "sender_user_id": { "type": "string", "description": "The broker whose mailbox the merge went out from." }, "subject": { "nullable": true, "description": "The subject of the email. Null if it had none.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When the merge is set to go out. Null if it went out at once.", "type": "string" }, "recipient_counts": { "type": "object", "properties": { "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies waiting to go out." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies the mail provider accepted." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies that could not go out." }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses BrokerPlus did not write to, because the person unsubscribed or withdrew consent." } }, "required": [ "queued", "sent", "failed", "skipped" ], "additionalProperties": false, "description": "How many addresses are in each state. Read each one with `GET /v1/mail-merges/{id}/recipients`." }, "created_at": { "type": "string", "description": "When the merge was sent or scheduled." }, "updated_at": { "type": "string", "description": "When the merge last changed." } }, "required": [ "object", "id", "sender_user_id", "subject", "scheduled_at", "recipient_counts", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The list has more than 500 addresses, or the message uses a merge field (VALIDATION_ERROR, TOKENS_NOT_SUPPORTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The mail merge could not be sent, for example because the mailbox was disconnected (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/mail-merges/{id}": { "get": { "operationId": "getMailMerge", "summary": "Retrieve a mail merge", "description": "One mail merge, with how many addresses are in each state.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "mail_merge", "description": "The type of this record. Always `mail_merge`.", "type": "string", "enum": [ "mail_merge" ] }, "id": { "type": "string", "description": "Stable identifier for the mail merge." }, "sender_user_id": { "type": "string", "description": "The broker whose mailbox the merge went out from." }, "subject": { "nullable": true, "description": "The subject of the email. Null if it had none.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When the merge is set to go out. Null if it went out at once.", "type": "string" }, "recipient_counts": { "type": "object", "properties": { "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies waiting to go out." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies the mail provider accepted." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Copies that could not go out." }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Addresses BrokerPlus did not write to, because the person unsubscribed or withdrew consent." } }, "required": [ "queued", "sent", "failed", "skipped" ], "additionalProperties": false, "description": "How many addresses are in each state. Read each one with `GET /v1/mail-merges/{id}/recipients`." }, "created_at": { "type": "string", "description": "When the merge was sent or scheduled." }, "updated_at": { "type": "string", "description": "When the merge last changed." } }, "required": [ "object", "id", "sender_user_id", "subject", "scheduled_at", "recipient_counts", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/mail-merges/{id}/recipients": { "get": { "operationId": "listMailMergeRecipients", "summary": "List the recipients of a mail merge", "description": "What became of each address in a mail merge, in the order they were added. The address itself is not kept: `communication_id` is the copy in the broker's Sent mail, and `contact_id` is the contact with that address.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "sent", "failed", "skipped" ] }, "description": "Only the recipients in this state." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mail_merge_recipient", "description": "The type of this record. Always `mail_merge_recipient`.", "type": "string", "enum": [ "mail_merge_recipient" ] }, "id": { "type": "string", "description": "Stable identifier for the recipient." }, "mail_merge_id": { "type": "string", "description": "The mail merge." }, "contact_id": { "nullable": true, "description": "The contact with this address. Null if no contact has it, or if more than one does. The address itself is not kept on the merge.", "type": "string" }, "communication_id": { "nullable": true, "description": "The copy sent to this address, in the broker's Sent mail. Null for a skipped or scheduled copy.", "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sent", "failed", "skipped" ], "description": "`queued`: waiting to go out. `sent`: the mail provider accepted it. `failed`: it could not go out, and `error` says why. `skipped`: the person unsubscribed or withdrew consent, so BrokerPlus did not write to them." }, "error": { "nullable": true, "description": "A short code for why the copy failed or was skipped, for example `no_consent`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the copy went out. Null until it does.", "type": "string" }, "created_at": { "type": "string", "description": "When the address was added to the merge." }, "updated_at": { "type": "string", "description": "When the recipient last changed." } }, "required": [ "object", "id", "mail_merge_id", "contact_id", "communication_id", "status", "error", "sent_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/teams": { "get": { "operationId": "listTeams", "summary": "List teams", "description": "The broker teams in this brokerage. Every team is owned by exactly one broker.", "tags": [ "Teams" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "team", "description": "The type of this record. Always `team`.", "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "description": "Stable identifier for the team." }, "name": { "type": "string", "description": "Team name as brokers see it." }, "broker_user_id": { "type": "string", "description": "The broker who owns the team. Exactly one, always." }, "is_archived": { "type": "boolean", "description": "Archived teams keep their records but take no new work." }, "created_at": { "type": "string", "description": "When the team was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "broker_user_id", "is_archived", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/teams/{id}": { "get": { "operationId": "getTeam", "summary": "Retrieve a team", "description": "A single team by id.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "team", "description": "The type of this record. Always `team`.", "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "description": "Stable identifier for the team." }, "name": { "type": "string", "description": "Team name as brokers see it." }, "broker_user_id": { "type": "string", "description": "The broker who owns the team. Exactly one, always." }, "is_archived": { "type": "boolean", "description": "Archived teams keep their records but take no new work." }, "created_at": { "type": "string", "description": "When the team was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "broker_user_id", "is_archived", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/teams/{id}/members": { "get": { "operationId": "listTeamMembers", "summary": "List a team's members", "description": "Who works this team and as what. The owner is the `broker`; everyone else is a `member` with the brokerage's own `title`. People who have left are excluded unless you ask for them.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send `true` to include people who have left the team." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The person. Resolve against `GET /users/{id}`." }, "team_id": { "type": "string", "description": "The team." }, "role": { "type": "string", "enum": [ "broker", "member" ], "description": "`broker` owns the team. `member` works on it." }, "title": { "nullable": true, "description": "The brokerage's own word for the seat, e.g. `Underwriter`. Null if none.", "type": "string" }, "is_active": { "type": "boolean", "description": "False once the person has left the team. Their records stay." }, "started_at": { "type": "string", "description": "When they joined the team." }, "ended_at": { "nullable": true, "description": "When they left. Null while active.", "type": "string" }, "created_at": { "type": "string", "description": "When the seat was added." }, "updated_at": { "type": "string", "description": "Last change to the seat." } }, "required": [ "user_id", "team_id", "role", "title", "is_active", "started_at", "ended_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/teams/{id}/note": { "get": { "operationId": "getTeamNote", "summary": "Read a team's shared note", "description": "The note that every member of the team sees and edits on their overview. Only a member of the team can read it.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "team_note", "description": "The type of this record. Always `team_note`.", "type": "string", "enum": [ "team_note" ] }, "team_id": { "type": "string", "description": "The team that the note belongs to. A team has one note." }, "team_name": { "type": "string", "description": "The team name, for display." }, "body": { "type": "string", "description": "The note, as HTML. Every member of the team reads and edits the same note on their overview. An empty string if nobody wrote one." }, "updated_at": { "nullable": true, "description": "When somebody last changed the note. Null if nobody wrote one.", "type": "string" } }, "required": [ "object", "team_id", "team_name", "body", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The team does not exist, or the broker is not a member of it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateTeamNote", "summary": "Replace a team's shared note", "description": "Replaces the whole note. Every member of the team sees the change on their overview. Nobody is notified, and a mention in the note does not notify the teammate. Only a member of the team can change it.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 50000, "description": "The whole note. It replaces the note. Plain text or HTML, up to 50,000 characters. Unsafe HTML is removed. Send an empty string to clear the note. A mention in the note does not notify the teammate." } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "team_note", "description": "The type of this record. Always `team_note`.", "type": "string", "enum": [ "team_note" ] }, "team_id": { "type": "string", "description": "The team that the note belongs to. A team has one note." }, "team_name": { "type": "string", "description": "The team name, for display." }, "body": { "type": "string", "description": "The note, as HTML. Every member of the team reads and edits the same note on their overview. An empty string if nobody wrote one." }, "updated_at": { "nullable": true, "description": "When somebody last changed the note. Null if nobody wrote one.", "type": "string" } }, "required": [ "object", "team_id", "team_name", "body", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The team does not exist, or the broker is not a member of it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments": { "get": { "operationId": "listAppointments", "summary": "List appointments", "description": "Calendar appointments, earliest first. Use `starts_after` and `starts_before` to fetch a window, which is what a calendar sync wants; use `updated_since` to fetch only what changed.", "tags": [ "Appointments" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "starts_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. Only appointments starting at or after it." }, { "name": "starts_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. Only appointments starting at or before it." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "appointment", "description": "The type of this record. Always `appointment`.", "type": "string", "enum": [ "appointment" ] }, "id": { "type": "string", "description": "Stable identifier for the appointment." }, "title": { "type": "string", "description": "What the appointment is called." }, "description": { "nullable": true, "description": "Longer detail, when there is any.", "type": "string" }, "start_at": { "type": "string", "description": "When it starts." }, "end_at": { "type": "string", "description": "When it ends." }, "all_day": { "type": "boolean", "description": "True for an all-day block. `start_at` and `end_at` still bound the day." }, "location": { "nullable": true, "description": "Free-text location.", "type": "string" }, "owner_id": { "type": "string", "description": "The broker whose calendar this sits on." }, "owner_name": { "nullable": true, "description": "The name of the broker whose calendar this sits on.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it relates to, when it names one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null when the appointment names no deal.", "type": "string" }, "source": { "type": "string", "description": "`app` for an appointment made in BrokerPlus, or the calendar it synced from." }, "conference_url": { "nullable": true, "description": "Video call link, when the appointment carries one.", "type": "string" }, "recurrence_rule": { "nullable": true, "description": "Repeat rule for a series, e.g. `FREQ=WEEKLY`. Null for one-off.", "type": "string" }, "ical_uid": { "nullable": true, "description": "The iCalendar UID the calendar provider gave the event. Use it to match the appointment to the same event in another calendar. Null on an appointment that never synced.", "type": "string" }, "shows_as_free": { "type": "boolean", "description": "True when the time does not count as busy, so a client can still book it. The broker's own choice wins over the synced calendar's." }, "created_at": { "type": "string", "description": "When the appointment was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "title", "description", "start_at", "end_at", "all_day", "location", "owner_id", "owner_name", "deal_id", "deal_name", "source", "conference_url", "recurrence_rule", "ical_uid", "shows_as_free", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAppointment", "summary": "Create an appointment", "description": "The appointment is created on the calendar of the broker your key acts as. `end_at` must be after `start_at`.", "tags": [ "Appointments" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Required." }, "start_at": { "type": "string", "description": "ISO 8601 start time. Required." }, "end_at": { "type": "string", "description": "ISO 8601 end time. Must be after `start_at`. Required." }, "description": { "description": "Longer detail.", "nullable": true, "type": "string", "maxLength": 20000 }, "location": { "description": "Free-text location.", "nullable": true, "type": "string", "maxLength": 500 }, "all_day": { "description": "Defaults to `false`.", "type": "boolean" }, "deal_id": { "description": "Relate the appointment to a deal in your brokerage.", "nullable": true, "type": "string" }, "conference_url": { "description": "Video call link.", "nullable": true, "type": "string" } }, "required": [ "title", "start_at", "end_at" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "appointment", "description": "The type of this record. Always `appointment`.", "type": "string", "enum": [ "appointment" ] }, "id": { "type": "string", "description": "Stable identifier for the appointment." }, "title": { "type": "string", "description": "What the appointment is called." }, "description": { "nullable": true, "description": "Longer detail, when there is any.", "type": "string" }, "start_at": { "type": "string", "description": "When it starts." }, "end_at": { "type": "string", "description": "When it ends." }, "all_day": { "type": "boolean", "description": "True for an all-day block. `start_at` and `end_at` still bound the day." }, "location": { "nullable": true, "description": "Free-text location.", "type": "string" }, "owner_id": { "type": "string", "description": "The broker whose calendar this sits on." }, "owner_name": { "nullable": true, "description": "The name of the broker whose calendar this sits on.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it relates to, when it names one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null when the appointment names no deal.", "type": "string" }, "source": { "type": "string", "description": "`app` for an appointment made in BrokerPlus, or the calendar it synced from." }, "conference_url": { "nullable": true, "description": "Video call link, when the appointment carries one.", "type": "string" }, "recurrence_rule": { "nullable": true, "description": "Repeat rule for a series, e.g. `FREQ=WEEKLY`. Null for one-off.", "type": "string" }, "ical_uid": { "nullable": true, "description": "The iCalendar UID the calendar provider gave the event. Use it to match the appointment to the same event in another calendar. Null on an appointment that never synced.", "type": "string" }, "shows_as_free": { "type": "boolean", "description": "True when the time does not count as busy, so a client can still book it. The broker's own choice wins over the synced calendar's." }, "created_at": { "type": "string", "description": "When the appointment was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "title", "description", "start_at", "end_at", "all_day", "location", "owner_id", "owner_name", "deal_id", "deal_name", "source", "conference_url", "recurrence_rule", "ical_uid", "shows_as_free", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments/{id}": { "get": { "operationId": "getAppointment", "summary": "Retrieve an appointment", "description": "A single appointment by id.", "tags": [ "Appointments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "appointment", "description": "The type of this record. Always `appointment`.", "type": "string", "enum": [ "appointment" ] }, "id": { "type": "string", "description": "Stable identifier for the appointment." }, "title": { "type": "string", "description": "What the appointment is called." }, "description": { "nullable": true, "description": "Longer detail, when there is any.", "type": "string" }, "start_at": { "type": "string", "description": "When it starts." }, "end_at": { "type": "string", "description": "When it ends." }, "all_day": { "type": "boolean", "description": "True for an all-day block. `start_at` and `end_at` still bound the day." }, "location": { "nullable": true, "description": "Free-text location.", "type": "string" }, "owner_id": { "type": "string", "description": "The broker whose calendar this sits on." }, "owner_name": { "nullable": true, "description": "The name of the broker whose calendar this sits on.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it relates to, when it names one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null when the appointment names no deal.", "type": "string" }, "source": { "type": "string", "description": "`app` for an appointment made in BrokerPlus, or the calendar it synced from." }, "conference_url": { "nullable": true, "description": "Video call link, when the appointment carries one.", "type": "string" }, "recurrence_rule": { "nullable": true, "description": "Repeat rule for a series, e.g. `FREQ=WEEKLY`. Null for one-off.", "type": "string" }, "ical_uid": { "nullable": true, "description": "The iCalendar UID the calendar provider gave the event. Use it to match the appointment to the same event in another calendar. Null on an appointment that never synced.", "type": "string" }, "shows_as_free": { "type": "boolean", "description": "True when the time does not count as busy, so a client can still book it. The broker's own choice wins over the synced calendar's." }, "created_at": { "type": "string", "description": "When the appointment was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "title", "description", "start_at", "end_at", "all_day", "location", "owner_id", "owner_name", "deal_id", "deal_name", "source", "conference_url", "recurrence_rule", "ical_uid", "shows_as_free", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateAppointment", "summary": "Update an appointment", "description": "Only the fields you send are changed. An appointment synced from an external calendar returns 409 - edit it in the calendar that owns it, or the next sync overwrites your change.", "tags": [ "Appointments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Required." }, "start_at": { "type": "string", "description": "ISO 8601 start time. Required." }, "end_at": { "type": "string", "description": "ISO 8601 end time. Must be after `start_at`. Required." }, "description": { "description": "Longer detail.", "nullable": true, "type": "string", "maxLength": 20000 }, "location": { "description": "Free-text location.", "nullable": true, "type": "string", "maxLength": 500 }, "all_day": { "description": "Defaults to `false`.", "type": "boolean" }, "deal_id": { "description": "Relate the appointment to a deal in your brokerage.", "nullable": true, "type": "string" }, "conference_url": { "description": "Video call link.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "appointment", "description": "The type of this record. Always `appointment`.", "type": "string", "enum": [ "appointment" ] }, "id": { "type": "string", "description": "Stable identifier for the appointment." }, "title": { "type": "string", "description": "What the appointment is called." }, "description": { "nullable": true, "description": "Longer detail, when there is any.", "type": "string" }, "start_at": { "type": "string", "description": "When it starts." }, "end_at": { "type": "string", "description": "When it ends." }, "all_day": { "type": "boolean", "description": "True for an all-day block. `start_at` and `end_at` still bound the day." }, "location": { "nullable": true, "description": "Free-text location.", "type": "string" }, "owner_id": { "type": "string", "description": "The broker whose calendar this sits on." }, "owner_name": { "nullable": true, "description": "The name of the broker whose calendar this sits on.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it relates to, when it names one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null when the appointment names no deal.", "type": "string" }, "source": { "type": "string", "description": "`app` for an appointment made in BrokerPlus, or the calendar it synced from." }, "conference_url": { "nullable": true, "description": "Video call link, when the appointment carries one.", "type": "string" }, "recurrence_rule": { "nullable": true, "description": "Repeat rule for a series, e.g. `FREQ=WEEKLY`. Null for one-off.", "type": "string" }, "ical_uid": { "nullable": true, "description": "The iCalendar UID the calendar provider gave the event. Use it to match the appointment to the same event in another calendar. Null on an appointment that never synced.", "type": "string" }, "shows_as_free": { "type": "boolean", "description": "True when the time does not count as busy, so a client can still book it. The broker's own choice wins over the synced calendar's." }, "created_at": { "type": "string", "description": "When the appointment was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "title", "description", "start_at", "end_at", "all_day", "location", "owner_id", "owner_name", "deal_id", "deal_name", "source", "conference_url", "recurrence_rule", "ical_uid", "shows_as_free", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteAppointment", "summary": "Delete an appointment", "description": "An appointment synced from an external calendar returns 409 for the same reason as update.", "tags": [ "Appointments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meeting-types": { "get": { "operationId": "listMeetingTypes", "summary": "List meeting types", "description": "The booking links that your key's broker hosts, and the team links of their teams. Use a meeting type's `id` to get open times and to book.", "tags": [ "Scheduling" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "meeting_type", "description": "The type of this record. Always `meeting_type`.", "type": "string", "enum": [ "meeting_type" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting type." }, "name": { "type": "string", "description": "The meeting type name that the client sees, e.g. `Discovery call`." }, "slug": { "type": "string", "description": "The unique part of the booking page URL." }, "description": { "nullable": true, "description": "Text that the booking page shows under the name.", "type": "string" }, "duration_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The length of each meeting, in minutes." }, "location": { "nullable": true, "description": "Where the meeting occurs, e.g. `Google Meet` or `Phone call`. Null when it is not set.", "type": "string" }, "enabled": { "type": "boolean", "description": "False when the broker turned the meeting type off. Clients cannot book it." }, "unlisted": { "type": "boolean", "description": "True when the meeting type is bookable by its URL only. The broker's booking page does not list it." }, "owner_user_id": { "nullable": true, "description": "The broker who hosts a personal meeting type. Null on a team meeting type.", "type": "string" }, "owner_name": { "nullable": true, "description": "The name of that broker. Null on a team meeting type.", "type": "string" }, "team_id": { "nullable": true, "description": "The team that hosts a team meeting type. BrokerPlus picks the host from the team members.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of that team. Null on a personal meeting type.", "type": "string" }, "booking_url": { "type": "string", "description": "The booking page URL. Send it to a client to let them pick a time." }, "min_notice_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The shortest time between now and the earliest bookable start." }, "max_advance_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days ahead a client can book." }, "buffer_before_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept before each meeting. No booking starts inside it." }, "buffer_after_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept after each meeting. No booking starts inside it." }, "slot_interval_minutes": { "nullable": true, "description": "The step between the start times offered, e.g. `30` offers 9:00, 9:30, 10:00. Null steps by `duration_minutes`.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "availability_hours": { "nullable": true, "description": "The weekly hours of this meeting type, one entry for each day. Null when it follows the host's own booking hours. `GET /availability` already applies them.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "required_license_class": { "nullable": true, "description": "The licence a host must hold to take the meeting. Null when the meeting type states none.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "required_province": { "nullable": true, "description": "The province the host must be licensed in, e.g. `ON`. Null when the meeting type states none.", "type": "string" }, "reminder_minutes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "When the client gets reminders, in minutes before the start, e.g. `[1440, 60]`. Empty sends none." }, "reminder_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "How each reminder goes out: `email`, `sms`, or both." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The broker's own order, ascending. Lists sort on it." }, "form_fields": { "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "required": [ "email", "phone", "notes", "guests" ], "additionalProperties": false, "description": "What the booking form collects. A booking must supply every `required` field." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Use this as `question_id` in a booking answer." }, "label": { "type": "string", "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "nullable": true, "description": "The allowed values of a `choice` question.", "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "description": "True when a booking must answer it." } }, "required": [ "id", "label", "type", "options", "required" ], "additionalProperties": false }, "description": "The broker's own questions on the booking form." }, "created_at": { "type": "string", "description": "When the meeting type was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "slug", "description", "duration_minutes", "location", "enabled", "unlisted", "owner_user_id", "owner_name", "team_id", "team_name", "booking_url", "min_notice_minutes", "max_advance_days", "buffer_before_minutes", "buffer_after_minutes", "slot_interval_minutes", "availability_hours", "required_license_class", "required_province", "reminder_minutes", "reminder_channels", "position", "form_fields", "questions", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createMeetingType", "summary": "Create a meeting type", "description": "Adds a booking link, the same as New meeting type in Settings > Booking. Without `team_id`, the key's broker hosts it. With `team_id`, BrokerPlus picks a host from `hosts` for each booking. The new meeting type goes to the end of the order. A meeting type sends nothing when you create it. Its confirmation and reminders go to the clients who book it later.", "tags": [ "Scheduling" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The meeting type name that the client sees, e.g. `Discovery call`." }, "description": { "description": "Text that the booking page shows under the name.", "nullable": true, "type": "string", "maxLength": 2000 }, "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 480, "description": "The length of each meeting, in minutes. 5 to 480." }, "slot_interval_minutes": { "description": "The step between the start times offered. Null steps by `duration_minutes`.", "nullable": true, "type": "integer", "minimum": 5, "maximum": 480 }, "availability_hours": { "description": "The weekly hours of this meeting type, one entry for each day. Null makes it follow the host's own booking hours (`GET /me/hours`).", "nullable": true, "minItems": 7, "maxItems": 7, "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. `540` is 9:00." }, "end_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. It must be after `start_minute`." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day, at most six. They must not overlap. Send an empty list for a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "buffer_before_minutes": { "description": "Free time kept before each meeting. 0 to 240.", "type": "integer", "minimum": 0, "maximum": 240 }, "buffer_after_minutes": { "description": "Free time kept after each meeting. 0 to 240.", "type": "integer", "minimum": 0, "maximum": 240 }, "location": { "description": "Where the meeting occurs, e.g. `Google Meet`.", "nullable": true, "type": "string", "maxLength": 200 }, "min_notice_minutes": { "description": "The shortest time between now and the earliest bookable start. 0 to 20160 (14 days).", "type": "integer", "minimum": 0, "maximum": 20160 }, "max_advance_days": { "description": "How many days ahead a client can book. 1 to 365.", "type": "integer", "minimum": 1, "maximum": 365 }, "enabled": { "description": "Send false to turn the meeting type off. Clients cannot book it.", "type": "boolean" }, "unlisted": { "description": "Send true to make the meeting type bookable by its URL only. The broker's booking page does not list it.", "type": "boolean" }, "reminder_minutes": { "description": "When the client gets reminders, in minutes before the start, at most six. An empty list sends none. A change applies to the reminders that BrokerPlus did not send yet.", "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 5, "maximum": 20160 } }, "reminder_channels": { "description": "How each reminder goes out: `email`, `sms`, or both. An empty list sends none.", "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] } }, "form_fields": { "description": "What the booking form collects. A field that you omit keeps its mode.", "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "additionalProperties": false }, "questions": { "description": "The broker's own questions on the booking form, in order, at most 20. Send the full list.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The id of a question that the meeting type has. Send it to keep the question. Omit it for a new question.", "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "description": "The allowed values of a `choice` question, at least one. Other types ignore it.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": { "description": "True when a booking must answer it. Defaults to false.", "type": "boolean" } }, "required": [ "label", "type" ], "additionalProperties": false } }, "team_id": { "description": "A team to host the meeting type. The key's broker must be able to write for that team. Omit it for a personal meeting type that the key's broker hosts.", "type": "string" }, "hosts": { "description": "The hosts of a team meeting type, at least one. A personal meeting type takes none.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "A broker who is an active member of `team_id`." }, "weight": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The share of bookings this host gets, compared with the other hosts. 1 to 100." } }, "required": [ "user_id", "weight" ], "additionalProperties": false } }, "required_license_class": { "description": "The licence a host must hold to take the meeting.", "nullable": true, "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "required_province": { "description": "The province the host must be licensed in, e.g. `ON`.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "duration_minutes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting_type", "description": "The type of this record. Always `meeting_type`.", "type": "string", "enum": [ "meeting_type" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting type." }, "name": { "type": "string", "description": "The meeting type name that the client sees, e.g. `Discovery call`." }, "slug": { "type": "string", "description": "The unique part of the booking page URL." }, "description": { "nullable": true, "description": "Text that the booking page shows under the name.", "type": "string" }, "duration_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The length of each meeting, in minutes." }, "location": { "nullable": true, "description": "Where the meeting occurs, e.g. `Google Meet` or `Phone call`. Null when it is not set.", "type": "string" }, "enabled": { "type": "boolean", "description": "False when the broker turned the meeting type off. Clients cannot book it." }, "unlisted": { "type": "boolean", "description": "True when the meeting type is bookable by its URL only. The broker's booking page does not list it." }, "owner_user_id": { "nullable": true, "description": "The broker who hosts a personal meeting type. Null on a team meeting type.", "type": "string" }, "owner_name": { "nullable": true, "description": "The name of that broker. Null on a team meeting type.", "type": "string" }, "team_id": { "nullable": true, "description": "The team that hosts a team meeting type. BrokerPlus picks the host from the team members.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of that team. Null on a personal meeting type.", "type": "string" }, "booking_url": { "type": "string", "description": "The booking page URL. Send it to a client to let them pick a time." }, "min_notice_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The shortest time between now and the earliest bookable start." }, "max_advance_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days ahead a client can book." }, "buffer_before_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept before each meeting. No booking starts inside it." }, "buffer_after_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept after each meeting. No booking starts inside it." }, "slot_interval_minutes": { "nullable": true, "description": "The step between the start times offered, e.g. `30` offers 9:00, 9:30, 10:00. Null steps by `duration_minutes`.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "availability_hours": { "nullable": true, "description": "The weekly hours of this meeting type, one entry for each day. Null when it follows the host's own booking hours. `GET /availability` already applies them.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "required_license_class": { "nullable": true, "description": "The licence a host must hold to take the meeting. Null when the meeting type states none.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "required_province": { "nullable": true, "description": "The province the host must be licensed in, e.g. `ON`. Null when the meeting type states none.", "type": "string" }, "reminder_minutes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "When the client gets reminders, in minutes before the start, e.g. `[1440, 60]`. Empty sends none." }, "reminder_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "How each reminder goes out: `email`, `sms`, or both." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The broker's own order, ascending. Lists sort on it." }, "form_fields": { "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "required": [ "email", "phone", "notes", "guests" ], "additionalProperties": false, "description": "What the booking form collects. A booking must supply every `required` field." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Use this as `question_id` in a booking answer." }, "label": { "type": "string", "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "nullable": true, "description": "The allowed values of a `choice` question.", "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "description": "True when a booking must answer it." } }, "required": [ "id", "label", "type", "options", "required" ], "additionalProperties": false }, "description": "The broker's own questions on the booking form." }, "created_at": { "type": "string", "description": "When the meeting type was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "slug", "description", "duration_minutes", "location", "enabled", "unlisted", "owner_user_id", "owner_name", "team_id", "team_name", "booking_url", "min_notice_minutes", "max_advance_days", "buffer_before_minutes", "buffer_after_minutes", "slot_interval_minutes", "availability_hours", "required_license_class", "required_province", "reminder_minutes", "reminder_channels", "position", "form_fields", "questions", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A value is out of range, a team meeting type has no hosts, a host is not an active member of the team, or a personal meeting type names hosts (VALIDATION_ERROR, EMPTY_ROSTER, NOT_A_MEMBER, PERSONAL_LINK_ROSTER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker cannot write for that team (TEAM_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The team is not in your brokerage (TEAM_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meeting-types/reorder": { "post": { "operationId": "reorderMeetingTypes", "summary": "Put meeting types in order", "description": "Sets the order of the meeting types, the same as a drag in Settings > Booking. The booking page lists them in this order. Returns the meeting types in the new order.", "tags": [ "Scheduling" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "Meeting type ids in the new order, first to last. An id that your key cannot change keeps its place." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "meeting_type", "description": "The type of this record. Always `meeting_type`.", "type": "string", "enum": [ "meeting_type" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting type." }, "name": { "type": "string", "description": "The meeting type name that the client sees, e.g. `Discovery call`." }, "slug": { "type": "string", "description": "The unique part of the booking page URL." }, "description": { "nullable": true, "description": "Text that the booking page shows under the name.", "type": "string" }, "duration_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The length of each meeting, in minutes." }, "location": { "nullable": true, "description": "Where the meeting occurs, e.g. `Google Meet` or `Phone call`. Null when it is not set.", "type": "string" }, "enabled": { "type": "boolean", "description": "False when the broker turned the meeting type off. Clients cannot book it." }, "unlisted": { "type": "boolean", "description": "True when the meeting type is bookable by its URL only. The broker's booking page does not list it." }, "owner_user_id": { "nullable": true, "description": "The broker who hosts a personal meeting type. Null on a team meeting type.", "type": "string" }, "owner_name": { "nullable": true, "description": "The name of that broker. Null on a team meeting type.", "type": "string" }, "team_id": { "nullable": true, "description": "The team that hosts a team meeting type. BrokerPlus picks the host from the team members.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of that team. Null on a personal meeting type.", "type": "string" }, "booking_url": { "type": "string", "description": "The booking page URL. Send it to a client to let them pick a time." }, "min_notice_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The shortest time between now and the earliest bookable start." }, "max_advance_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days ahead a client can book." }, "buffer_before_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept before each meeting. No booking starts inside it." }, "buffer_after_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept after each meeting. No booking starts inside it." }, "slot_interval_minutes": { "nullable": true, "description": "The step between the start times offered, e.g. `30` offers 9:00, 9:30, 10:00. Null steps by `duration_minutes`.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "availability_hours": { "nullable": true, "description": "The weekly hours of this meeting type, one entry for each day. Null when it follows the host's own booking hours. `GET /availability` already applies them.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "required_license_class": { "nullable": true, "description": "The licence a host must hold to take the meeting. Null when the meeting type states none.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "required_province": { "nullable": true, "description": "The province the host must be licensed in, e.g. `ON`. Null when the meeting type states none.", "type": "string" }, "reminder_minutes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "When the client gets reminders, in minutes before the start, e.g. `[1440, 60]`. Empty sends none." }, "reminder_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "How each reminder goes out: `email`, `sms`, or both." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The broker's own order, ascending. Lists sort on it." }, "form_fields": { "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "required": [ "email", "phone", "notes", "guests" ], "additionalProperties": false, "description": "What the booking form collects. A booking must supply every `required` field." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Use this as `question_id` in a booking answer." }, "label": { "type": "string", "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "nullable": true, "description": "The allowed values of a `choice` question.", "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "description": "True when a booking must answer it." } }, "required": [ "id", "label", "type", "options", "required" ], "additionalProperties": false }, "description": "The broker's own questions on the booking form." }, "created_at": { "type": "string", "description": "When the meeting type was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "slug", "description", "duration_minutes", "location", "enabled", "unlisted", "owner_user_id", "owner_name", "team_id", "team_name", "booking_url", "min_notice_minutes", "max_advance_days", "buffer_before_minutes", "buffer_after_minutes", "slot_interval_minutes", "availability_hours", "required_license_class", "required_province", "reminder_minutes", "reminder_channels", "position", "form_fields", "questions", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meeting-types/{id}": { "patch": { "operationId": "updateMeetingType", "summary": "Update a meeting type", "description": "Changes the length, hours, buffers, notice, questions, reminders, or other settings of a meeting type. A change applies to the bookings made after it. A booking that a client already made keeps its time. You can change a personal meeting type of the key's broker, or a team meeting type of a team that the broker can write for. You cannot change the team or the hosts here.", "tags": [ "Scheduling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The meeting type name that the client sees.", "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "description": "The unique part of the booking page URL. A new slug stops the old URL. BrokerPlus does not change the slug when the name changes.", "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "Text that the booking page shows under the name.", "nullable": true, "type": "string", "maxLength": 2000 }, "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 480, "description": "The length of each meeting, in minutes. 5 to 480." }, "slot_interval_minutes": { "description": "The step between the start times offered. Null steps by `duration_minutes`.", "nullable": true, "type": "integer", "minimum": 5, "maximum": 480 }, "availability_hours": { "description": "The weekly hours of this meeting type, one entry for each day. Null makes it follow the host's own booking hours (`GET /me/hours`).", "nullable": true, "minItems": 7, "maxItems": 7, "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. `540` is 9:00." }, "end_minute": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minutes after midnight, in the broker's time zone. It must be after `start_minute`." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day, at most six. They must not overlap. Send an empty list for a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "buffer_before_minutes": { "description": "Free time kept before each meeting. 0 to 240.", "type": "integer", "minimum": 0, "maximum": 240 }, "buffer_after_minutes": { "description": "Free time kept after each meeting. 0 to 240.", "type": "integer", "minimum": 0, "maximum": 240 }, "location": { "description": "Where the meeting occurs, e.g. `Google Meet`.", "nullable": true, "type": "string", "maxLength": 200 }, "min_notice_minutes": { "description": "The shortest time between now and the earliest bookable start. 0 to 20160 (14 days).", "type": "integer", "minimum": 0, "maximum": 20160 }, "max_advance_days": { "description": "How many days ahead a client can book. 1 to 365.", "type": "integer", "minimum": 1, "maximum": 365 }, "enabled": { "description": "Send false to turn the meeting type off. Clients cannot book it.", "type": "boolean" }, "unlisted": { "description": "Send true to make the meeting type bookable by its URL only. The broker's booking page does not list it.", "type": "boolean" }, "reminder_minutes": { "description": "When the client gets reminders, in minutes before the start, at most six. An empty list sends none. A change applies to the reminders that BrokerPlus did not send yet.", "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 5, "maximum": 20160 } }, "reminder_channels": { "description": "How each reminder goes out: `email`, `sms`, or both. An empty list sends none.", "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] } }, "form_fields": { "description": "What the booking form collects. A field that you omit keeps its mode.", "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "additionalProperties": false }, "questions": { "description": "The broker's own questions on the booking form, in order, at most 20. Send the full list.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The id of a question that the meeting type has. Send it to keep the question. Omit it for a new question.", "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "description": "The allowed values of a `choice` question, at least one. Other types ignore it.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": { "description": "True when a booking must answer it. Defaults to false.", "type": "boolean" } }, "required": [ "label", "type" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting_type", "description": "The type of this record. Always `meeting_type`.", "type": "string", "enum": [ "meeting_type" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting type." }, "name": { "type": "string", "description": "The meeting type name that the client sees, e.g. `Discovery call`." }, "slug": { "type": "string", "description": "The unique part of the booking page URL." }, "description": { "nullable": true, "description": "Text that the booking page shows under the name.", "type": "string" }, "duration_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The length of each meeting, in minutes." }, "location": { "nullable": true, "description": "Where the meeting occurs, e.g. `Google Meet` or `Phone call`. Null when it is not set.", "type": "string" }, "enabled": { "type": "boolean", "description": "False when the broker turned the meeting type off. Clients cannot book it." }, "unlisted": { "type": "boolean", "description": "True when the meeting type is bookable by its URL only. The broker's booking page does not list it." }, "owner_user_id": { "nullable": true, "description": "The broker who hosts a personal meeting type. Null on a team meeting type.", "type": "string" }, "owner_name": { "nullable": true, "description": "The name of that broker. Null on a team meeting type.", "type": "string" }, "team_id": { "nullable": true, "description": "The team that hosts a team meeting type. BrokerPlus picks the host from the team members.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of that team. Null on a personal meeting type.", "type": "string" }, "booking_url": { "type": "string", "description": "The booking page URL. Send it to a client to let them pick a time." }, "min_notice_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The shortest time between now and the earliest bookable start." }, "max_advance_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days ahead a client can book." }, "buffer_before_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept before each meeting. No booking starts inside it." }, "buffer_after_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Free time kept after each meeting. No booking starts inside it." }, "slot_interval_minutes": { "nullable": true, "description": "The step between the start times offered, e.g. `30` offers 9:00, 9:30, 10:00. Null steps by `duration_minutes`.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "availability_hours": { "nullable": true, "description": "The weekly hours of this meeting type, one entry for each day. Null when it follows the host's own booking hours. `GET /availability` already applies them.", "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 is Sunday, 6 is Saturday." }, "windows": { "type": "array", "items": { "type": "object", "properties": { "start_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." }, "end_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Minutes after midnight, in the host's time zone." } }, "required": [ "start_minute", "end_minute" ], "additionalProperties": false }, "description": "The open windows of the day. Empty on a closed day." } }, "required": [ "day_of_week", "windows" ], "additionalProperties": false } }, "required_license_class": { "nullable": true, "description": "The licence a host must hold to take the meeting. Null when the meeting type states none.", "type": "string", "enum": [ "unlicensed", "agent_level_1", "agent_level_2", "broker", "principal_broker" ] }, "required_province": { "nullable": true, "description": "The province the host must be licensed in, e.g. `ON`. Null when the meeting type states none.", "type": "string" }, "reminder_minutes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "When the client gets reminders, in minutes before the start, e.g. `[1440, 60]`. Empty sends none." }, "reminder_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "How each reminder goes out: `email`, `sms`, or both." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The broker's own order, ascending. Lists sort on it." }, "form_fields": { "type": "object", "properties": { "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "phone": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "notes": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." }, "guests": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "`required`, `optional`, or `hidden`. A `hidden` field is not collected on this meeting type." } }, "required": [ "email", "phone", "notes", "guests" ], "additionalProperties": false, "description": "What the booking form collects. A booking must supply every `required` field." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Use this as `question_id` in a booking answer." }, "label": { "type": "string", "description": "The question text." }, "type": { "type": "string", "enum": [ "text", "choice" ], "description": "`text` for free text. `choice` for one value from `options`." }, "options": { "nullable": true, "description": "The allowed values of a `choice` question.", "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean", "description": "True when a booking must answer it." } }, "required": [ "id", "label", "type", "options", "required" ], "additionalProperties": false }, "description": "The broker's own questions on the booking form." }, "created_at": { "type": "string", "description": "When the meeting type was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "slug", "description", "duration_minutes", "location", "enabled", "unlisted", "owner_user_id", "owner_name", "team_id", "team_name", "booking_url", "min_notice_minutes", "max_advance_days", "buffer_before_minutes", "buffer_after_minutes", "slot_interval_minutes", "availability_hours", "required_license_class", "required_province", "reminder_minutes", "reminder_channels", "position", "form_fields", "questions", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A value is out of range, or the slug is not valid (VALIDATION_ERROR, INVALID_SLUG).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The meeting type is not one that your key can change (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another meeting type uses this slug (SLUG_TAKEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteMeetingType", "summary": "Delete a meeting type", "description": "Deletes a booking link, the same as Delete in Settings > Booking. Its booking URL stops. The appointments that clients already booked stay on the calendar, and BrokerPlus does not tell the clients. To stop new bookings and keep the link, send `enabled: false` with `PATCH /meeting-types/{id}`.", "tags": [ "Scheduling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The meeting type is not one that your key can change (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/availability": { "get": { "operationId": "getAvailability", "summary": "Get open times", "description": "The open start times of a meeting type, earliest first. BrokerPlus calculates them the same way as the booking page: each host's hours in their own time zone, split shifts, blocked days, buffers, minimum notice, and their busy calendar. The window is 14 days from `from` by default, and at most 31 days.", "tags": [ "Scheduling" ], "parameters": [ { "name": "meeting_type_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required. The meeting type to get open times for." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. The start of the window. Defaults to now." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp. The end of the window. Defaults to 14 days after `from`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "meeting_type_id": { "type": "string", "description": "The meeting type the slots are for." }, "from": { "type": "string", "description": "The start of the window that was searched." }, "to": { "type": "string", "description": "The end of the window that was searched." }, "slots": { "type": "array", "items": { "type": "object", "properties": { "start_at": { "type": "string", "description": "When the meeting starts. Send this value as `start_at` to book it." }, "end_at": { "type": "string", "description": "When the meeting ends." } }, "required": [ "start_at", "end_at" ], "additionalProperties": false }, "description": "Every open start in the window, earliest first. The booking page shows the same slots." } }, "required": [ "meeting_type_id", "from", "to", "slots" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The meeting type is turned off (MEETING_TYPE_DISABLED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments/{id}/booking": { "get": { "operationId": "getBooking", "summary": "Retrieve the booking on an appointment", "description": "What was booked into an appointment through a meeting type: the meeting type, the host, the client, their answers, and whether it was moved or canceled. Read it after a booking, move, or cancellation. A canceled booking stays readable with `status` `canceled`.", "tags": [ "Scheduling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "booking", "description": "The type of this record. Always `booking`.", "type": "string", "enum": [ "booking" ] }, "id": { "type": "string", "description": "Stable identifier for the booking." }, "appointment_id": { "nullable": true, "description": "The appointment on the host's calendar. Use it with `/appointments/{id}/reschedule` and `/cancel`.", "type": "string" }, "meeting_type_id": { "type": "string", "description": "The meeting type that was booked." }, "meeting_type_name": { "type": "string", "description": "The name of that meeting type." }, "status": { "type": "string", "enum": [ "confirmed", "canceled" ], "description": "`canceled` frees the slot. A canceled booking stays readable." }, "start_at": { "type": "string", "description": "When the meeting starts." }, "end_at": { "type": "string", "description": "When the meeting ends." }, "host_user_id": { "type": "string", "description": "The broker who hosts the meeting." }, "host_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact who was booked. Null when BrokerPlus could not match the guest to a contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "guest_name": { "type": "string", "description": "The guest name on the booking, as the confirmation shows it." }, "guest_email": { "nullable": true, "description": "Where the confirmation goes. Null when the guest gave no email.", "type": "string" }, "guest_phone": { "nullable": true, "description": "The guest phone number, in E.164 format.", "type": "string" }, "additional_guest_emails": { "type": "array", "items": { "type": "string" }, "description": "Other people the guest invited." }, "client_timezone": { "type": "string", "description": "The IANA time zone that the client sees the meeting in." }, "notes": { "nullable": true, "description": "The notes on the booking form.", "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "description": "The question that was answered." }, "label": { "type": "string", "description": "The question text at the time of the booking." }, "value": { "type": "string", "description": "The answer." } }, "required": [ "question_id", "label", "value" ], "additionalProperties": false }, "description": "Answers to the meeting type's questions." }, "confirmation_sent_at": { "nullable": true, "description": "When BrokerPlus sent the confirmation email to the guest. Null until it sends.", "type": "string" }, "rescheduled_at": { "nullable": true, "description": "When the booking last moved. Null if it never moved.", "type": "string" }, "canceled_at": { "nullable": true, "description": "When the booking was canceled. Null while it is confirmed.", "type": "string" }, "created_at": { "type": "string", "description": "When the booking was made." } }, "required": [ "object", "id", "appointment_id", "meeting_type_id", "meeting_type_name", "status", "start_at", "end_at", "host_user_id", "host_name", "contact_id", "contact_name", "guest_name", "guest_email", "guest_phone", "additional_guest_emails", "client_timezone", "notes", "answers", "confirmation_sent_at", "rescheduled_at", "canceled_at", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The appointment was not booked into a meeting type, or you cannot reach it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments/book": { "post": { "operationId": "bookMeeting", "summary": "Book a contact into a meeting type", "description": "Books a contact into an open time now, the same way the client's booking page does: BrokerPlus picks the host, puts the appointment on the host's calendar, and **sends the client the booking confirmation email**. The response is the booking. Get open times from `GET /availability` first. A key with the `no_sending` limit cannot use this endpoint. Supports `Idempotency-Key`.", "tags": [ "Scheduling" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "meeting_type_id": { "type": "string", "minLength": 1, "description": "The meeting type to book. Required." }, "contact_id": { "type": "string", "minLength": 1, "description": "The contact to book. The booking uses the contact's name, email, and phone. Required." }, "start_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 start time. It must be a slot that `GET /availability` returns. Required." }, "client_timezone": { "type": "string", "minLength": 1, "maxLength": 120, "description": "An IANA time zone, e.g. `America/Toronto`. The confirmation email shows the time in this zone. Required." }, "notes": { "description": "Notes for the meeting. Ignored when the form hides notes.", "nullable": true, "type": "string", "maxLength": 2000 }, "additional_guest_emails": { "description": "Up to 10 other people to invite. Ignored when the form hides guests.", "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "answers": { "description": "Answers to the meeting type's questions. Every `required` question needs one.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of a question on the meeting type." }, "value": { "type": "string", "maxLength": 2000, "description": "The answer. A `choice` answer must be one of the `options`." } }, "required": [ "question_id", "value" ], "additionalProperties": false } } }, "required": [ "meeting_type_id", "contact_id", "start_at", "client_timezone" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "booking", "description": "The type of this record. Always `booking`.", "type": "string", "enum": [ "booking" ] }, "id": { "type": "string", "description": "Stable identifier for the booking." }, "appointment_id": { "nullable": true, "description": "The appointment on the host's calendar. Use it with `/appointments/{id}/reschedule` and `/cancel`.", "type": "string" }, "meeting_type_id": { "type": "string", "description": "The meeting type that was booked." }, "meeting_type_name": { "type": "string", "description": "The name of that meeting type." }, "status": { "type": "string", "enum": [ "confirmed", "canceled" ], "description": "`canceled` frees the slot. A canceled booking stays readable." }, "start_at": { "type": "string", "description": "When the meeting starts." }, "end_at": { "type": "string", "description": "When the meeting ends." }, "host_user_id": { "type": "string", "description": "The broker who hosts the meeting." }, "host_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact who was booked. Null when BrokerPlus could not match the guest to a contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "guest_name": { "type": "string", "description": "The guest name on the booking, as the confirmation shows it." }, "guest_email": { "nullable": true, "description": "Where the confirmation goes. Null when the guest gave no email.", "type": "string" }, "guest_phone": { "nullable": true, "description": "The guest phone number, in E.164 format.", "type": "string" }, "additional_guest_emails": { "type": "array", "items": { "type": "string" }, "description": "Other people the guest invited." }, "client_timezone": { "type": "string", "description": "The IANA time zone that the client sees the meeting in." }, "notes": { "nullable": true, "description": "The notes on the booking form.", "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "description": "The question that was answered." }, "label": { "type": "string", "description": "The question text at the time of the booking." }, "value": { "type": "string", "description": "The answer." } }, "required": [ "question_id", "label", "value" ], "additionalProperties": false }, "description": "Answers to the meeting type's questions." }, "confirmation_sent_at": { "nullable": true, "description": "When BrokerPlus sent the confirmation email to the guest. Null until it sends.", "type": "string" }, "rescheduled_at": { "nullable": true, "description": "When the booking last moved. Null if it never moved.", "type": "string" }, "canceled_at": { "nullable": true, "description": "When the booking was canceled. Null while it is confirmed.", "type": "string" }, "created_at": { "type": "string", "description": "When the booking was made." } }, "required": [ "object", "id", "appointment_id", "meeting_type_id", "meeting_type_name", "status", "start_at", "end_at", "host_user_id", "host_name", "contact_id", "contact_name", "guest_name", "guest_email", "guest_phone", "additional_guest_emails", "client_timezone", "notes", "answers", "confirmation_sent_at", "rescheduled_at", "canceled_at", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The contact has no email or phone that the meeting type requires (CONTACT_INCOMPLETE), or a required answer is missing (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The time is not open, or another booking took it first (SLOT_TAKEN, HOST_DOUBLE_BOOKED, NOT_SENT). The meeting type is turned off (MEETING_TYPE_DISABLED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments/{id}/reschedule": { "post": { "operationId": "rescheduleBooking", "summary": "Move a booked appointment", "description": "Moves an appointment that was booked into a meeting type to another time with the same host, now. BrokerPlus **sends the client an email** about the new time, the same one the client gets when they move it themselves. The response is the booking. A key with the `no_sending` limit cannot use this endpoint.", "tags": [ "Scheduling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 new start time. It must be a slot that `GET /availability` returns for the same host." } }, "required": [ "start_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "booking", "description": "The type of this record. Always `booking`.", "type": "string", "enum": [ "booking" ] }, "id": { "type": "string", "description": "Stable identifier for the booking." }, "appointment_id": { "nullable": true, "description": "The appointment on the host's calendar. Use it with `/appointments/{id}/reschedule` and `/cancel`.", "type": "string" }, "meeting_type_id": { "type": "string", "description": "The meeting type that was booked." }, "meeting_type_name": { "type": "string", "description": "The name of that meeting type." }, "status": { "type": "string", "enum": [ "confirmed", "canceled" ], "description": "`canceled` frees the slot. A canceled booking stays readable." }, "start_at": { "type": "string", "description": "When the meeting starts." }, "end_at": { "type": "string", "description": "When the meeting ends." }, "host_user_id": { "type": "string", "description": "The broker who hosts the meeting." }, "host_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact who was booked. Null when BrokerPlus could not match the guest to a contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "guest_name": { "type": "string", "description": "The guest name on the booking, as the confirmation shows it." }, "guest_email": { "nullable": true, "description": "Where the confirmation goes. Null when the guest gave no email.", "type": "string" }, "guest_phone": { "nullable": true, "description": "The guest phone number, in E.164 format.", "type": "string" }, "additional_guest_emails": { "type": "array", "items": { "type": "string" }, "description": "Other people the guest invited." }, "client_timezone": { "type": "string", "description": "The IANA time zone that the client sees the meeting in." }, "notes": { "nullable": true, "description": "The notes on the booking form.", "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "description": "The question that was answered." }, "label": { "type": "string", "description": "The question text at the time of the booking." }, "value": { "type": "string", "description": "The answer." } }, "required": [ "question_id", "label", "value" ], "additionalProperties": false }, "description": "Answers to the meeting type's questions." }, "confirmation_sent_at": { "nullable": true, "description": "When BrokerPlus sent the confirmation email to the guest. Null until it sends.", "type": "string" }, "rescheduled_at": { "nullable": true, "description": "When the booking last moved. Null if it never moved.", "type": "string" }, "canceled_at": { "nullable": true, "description": "When the booking was canceled. Null while it is confirmed.", "type": "string" }, "created_at": { "type": "string", "description": "When the booking was made." } }, "required": [ "object", "id", "appointment_id", "meeting_type_id", "meeting_type_name", "status", "start_at", "end_at", "host_user_id", "host_name", "contact_id", "contact_name", "guest_name", "guest_email", "guest_phone", "additional_guest_emails", "client_timezone", "notes", "answers", "confirmation_sent_at", "rescheduled_at", "canceled_at", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The time is not open for this host (SLOT_TAKEN, HOST_DOUBLE_BOOKED, NOT_SENT), the booking is canceled (BOOKING_CANCELED), or the appointment was not booked into a meeting type (NOT_A_BOOKING).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/appointments/{id}/cancel": { "post": { "operationId": "cancelBooking", "summary": "Cancel a booked appointment", "description": "Cancels an appointment that was booked into a meeting type, now. BrokerPlus frees the time, removes the appointment from the calendar, and **sends the client a cancellation email**. The response is the booking, with `status` `canceled`. A key with the `no_sending` limit cannot use this endpoint.", "tags": [ "Scheduling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "booking", "description": "The type of this record. Always `booking`.", "type": "string", "enum": [ "booking" ] }, "id": { "type": "string", "description": "Stable identifier for the booking." }, "appointment_id": { "nullable": true, "description": "The appointment on the host's calendar. Use it with `/appointments/{id}/reschedule` and `/cancel`.", "type": "string" }, "meeting_type_id": { "type": "string", "description": "The meeting type that was booked." }, "meeting_type_name": { "type": "string", "description": "The name of that meeting type." }, "status": { "type": "string", "enum": [ "confirmed", "canceled" ], "description": "`canceled` frees the slot. A canceled booking stays readable." }, "start_at": { "type": "string", "description": "When the meeting starts." }, "end_at": { "type": "string", "description": "When the meeting ends." }, "host_user_id": { "type": "string", "description": "The broker who hosts the meeting." }, "host_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact who was booked. Null when BrokerPlus could not match the guest to a contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact.", "type": "string" }, "guest_name": { "type": "string", "description": "The guest name on the booking, as the confirmation shows it." }, "guest_email": { "nullable": true, "description": "Where the confirmation goes. Null when the guest gave no email.", "type": "string" }, "guest_phone": { "nullable": true, "description": "The guest phone number, in E.164 format.", "type": "string" }, "additional_guest_emails": { "type": "array", "items": { "type": "string" }, "description": "Other people the guest invited." }, "client_timezone": { "type": "string", "description": "The IANA time zone that the client sees the meeting in." }, "notes": { "nullable": true, "description": "The notes on the booking form.", "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "description": "The question that was answered." }, "label": { "type": "string", "description": "The question text at the time of the booking." }, "value": { "type": "string", "description": "The answer." } }, "required": [ "question_id", "label", "value" ], "additionalProperties": false }, "description": "Answers to the meeting type's questions." }, "confirmation_sent_at": { "nullable": true, "description": "When BrokerPlus sent the confirmation email to the guest. Null until it sends.", "type": "string" }, "rescheduled_at": { "nullable": true, "description": "When the booking last moved. Null if it never moved.", "type": "string" }, "canceled_at": { "nullable": true, "description": "When the booking was canceled. Null while it is confirmed.", "type": "string" }, "created_at": { "type": "string", "description": "When the booking was made." } }, "required": [ "object", "id", "appointment_id", "meeting_type_id", "meeting_type_name", "status", "start_at", "end_at", "host_user_id", "host_name", "contact_id", "contact_name", "guest_name", "guest_email", "guest_phone", "additional_guest_emails", "client_timezone", "notes", "answers", "confirmation_sent_at", "rescheduled_at", "canceled_at", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The appointment was not booked into a meeting type (NOT_A_BOOKING), so use `DELETE /appointments/{id}`, or it is already canceled (BOOKING_CANCELED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/submissions": { "get": { "operationId": "listSubmissions", "summary": "List submissions", "description": "Lender submissions, newest first, from both rails: sent through BrokerPlus (`source: brokerplus`) and mirrored from the connected Finmo account (`source: finmo`). A deal can be submitted more than once; `attempt` numbers the BrokerPlus ones.", "tags": [ "Submissions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by submission status." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only submissions on this deal." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "brokerplus", "finmo" ] }, "description": "Only submissions from this source: `brokerplus` or `finmo`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "submission", "description": "The type of this record. Always `submission`.", "type": "string", "enum": [ "submission" ] }, "id": { "type": "string", "description": "Stable identifier for the submission." }, "source": { "type": "string", "enum": [ "brokerplus", "finmo" ], "description": "`brokerplus` was sent through BrokerPlus. `finmo` is mirrored from the connected Finmo account." }, "deal_id": { "type": "string", "description": "The deal that was submitted." }, "lender_id": { "nullable": true, "description": "The lender it went to. Resolve through `GET /lenders`; the lender's `source` matches this submission's.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name at submission time, for reading only.", "type": "string" }, "product": { "nullable": true, "description": "Display name of the product chosen, for reading only.", "type": "string" }, "attempt": { "nullable": true, "description": "Submissions to the same deal are numbered. 1 is the first. Null on a Finmo submission.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "nullable": true, "description": "Where the submission stands, e.g. `draft`, `submitted`.", "type": "string" }, "lender_status": { "nullable": true, "description": "The lender's answer on a Finmo submission: `approved`, `declined`, `cancelled`, `incomplete`, `pending`, or `submitted`. Null on a BrokerPlus submission; read its decisions instead.", "type": "string" }, "application_number": { "nullable": true, "description": "The lender's application number, once one is issued.", "type": "string" }, "lender_ref_number": { "nullable": true, "description": "The lender's own reference, when they return one.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it went to the lender. Null while still a draft.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the broker marked the submission funded in Finmo. Null elsewhere.", "type": "string" }, "loan_amount": { "nullable": true, "description": "Principal requested, in dollars, on a Finmo submission.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate requested, as a PERCENT (`5.25` means 5.25%), on a Finmo submission.", "type": "number" }, "term_months": { "nullable": true, "description": "Term requested, in months, on a Finmo submission.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "submitted_by_id": { "nullable": true, "description": "The broker who submitted it. Null on a Finmo submission.", "type": "string" }, "submitted_by_name": { "nullable": true, "description": "The submitting broker's name. Null on a Finmo submission.", "type": "string" }, "failure_reason": { "nullable": true, "description": "Why the last transmission failed, when one did.", "type": "string" }, "cover_note": { "nullable": true, "description": "The note to the underwriter that goes with the file. Null on a Finmo submission.", "type": "string" }, "penalty_capitalized": { "nullable": true, "description": "On a refinance or a switch, `true` when the old lender's penalty is added to the new mortgage rather than paid at closing. Null on a Finmo submission.", "type": "boolean" }, "simulated": { "type": "boolean", "description": "`true` when the submission was a test that never reached a lender. Its numbers are made up. Always `false` on a Finmo submission." }, "validated_at": { "nullable": true, "description": "When the file last passed BrokerPlus's checks before sending. Null on a Finmo submission.", "type": "string" }, "goal": { "nullable": true, "description": "What the file asks for, in Finmo's words, e.g. `purchase` or `refinance`. Null on a BrokerPlus submission.", "type": "string" }, "approval_type": { "nullable": true, "description": "The kind of approval asked for, in Finmo's words. Null on a BrokerPlus submission.", "type": "string" }, "gds": { "nullable": true, "description": "Gross debt service the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "tds": { "nullable": true, "description": "Total debt service the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan to value the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "created_at": { "type": "string", "description": "When the submission was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "source", "deal_id", "lender_id", "lender_name", "product", "attempt", "status", "lender_status", "application_number", "lender_ref_number", "submitted_at", "funded_at", "loan_amount", "interest_rate", "term_months", "submitted_by_id", "submitted_by_name", "failure_reason", "cover_note", "penalty_capitalized", "simulated", "validated_at", "goal", "approval_type", "gds", "tds", "ltv", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/submissions/{id}": { "get": { "operationId": "getSubmission", "summary": "Retrieve a submission", "description": "A single submission by id.", "tags": [ "Submissions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "submission", "description": "The type of this record. Always `submission`.", "type": "string", "enum": [ "submission" ] }, "id": { "type": "string", "description": "Stable identifier for the submission." }, "source": { "type": "string", "enum": [ "brokerplus", "finmo" ], "description": "`brokerplus` was sent through BrokerPlus. `finmo` is mirrored from the connected Finmo account." }, "deal_id": { "type": "string", "description": "The deal that was submitted." }, "lender_id": { "nullable": true, "description": "The lender it went to. Resolve through `GET /lenders`; the lender's `source` matches this submission's.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name at submission time, for reading only.", "type": "string" }, "product": { "nullable": true, "description": "Display name of the product chosen, for reading only.", "type": "string" }, "attempt": { "nullable": true, "description": "Submissions to the same deal are numbered. 1 is the first. Null on a Finmo submission.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "nullable": true, "description": "Where the submission stands, e.g. `draft`, `submitted`.", "type": "string" }, "lender_status": { "nullable": true, "description": "The lender's answer on a Finmo submission: `approved`, `declined`, `cancelled`, `incomplete`, `pending`, or `submitted`. Null on a BrokerPlus submission; read its decisions instead.", "type": "string" }, "application_number": { "nullable": true, "description": "The lender's application number, once one is issued.", "type": "string" }, "lender_ref_number": { "nullable": true, "description": "The lender's own reference, when they return one.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When it went to the lender. Null while still a draft.", "type": "string" }, "funded_at": { "nullable": true, "description": "When the broker marked the submission funded in Finmo. Null elsewhere.", "type": "string" }, "loan_amount": { "nullable": true, "description": "Principal requested, in dollars, on a Finmo submission.", "type": "number" }, "interest_rate": { "nullable": true, "description": "Rate requested, as a PERCENT (`5.25` means 5.25%), on a Finmo submission.", "type": "number" }, "term_months": { "nullable": true, "description": "Term requested, in months, on a Finmo submission.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "submitted_by_id": { "nullable": true, "description": "The broker who submitted it. Null on a Finmo submission.", "type": "string" }, "submitted_by_name": { "nullable": true, "description": "The submitting broker's name. Null on a Finmo submission.", "type": "string" }, "failure_reason": { "nullable": true, "description": "Why the last transmission failed, when one did.", "type": "string" }, "cover_note": { "nullable": true, "description": "The note to the underwriter that goes with the file. Null on a Finmo submission.", "type": "string" }, "penalty_capitalized": { "nullable": true, "description": "On a refinance or a switch, `true` when the old lender's penalty is added to the new mortgage rather than paid at closing. Null on a Finmo submission.", "type": "boolean" }, "simulated": { "type": "boolean", "description": "`true` when the submission was a test that never reached a lender. Its numbers are made up. Always `false` on a Finmo submission." }, "validated_at": { "nullable": true, "description": "When the file last passed BrokerPlus's checks before sending. Null on a Finmo submission.", "type": "string" }, "goal": { "nullable": true, "description": "What the file asks for, in Finmo's words, e.g. `purchase` or `refinance`. Null on a BrokerPlus submission.", "type": "string" }, "approval_type": { "nullable": true, "description": "The kind of approval asked for, in Finmo's words. Null on a BrokerPlus submission.", "type": "string" }, "gds": { "nullable": true, "description": "Gross debt service the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "tds": { "nullable": true, "description": "Total debt service the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan to value the lender was sent, as a PERCENT. Set on a Finmo submission only.", "type": "number" }, "created_at": { "type": "string", "description": "When the submission was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "source", "deal_id", "lender_id", "lender_name", "product", "attempt", "status", "lender_status", "application_number", "lender_ref_number", "submitted_at", "funded_at", "loan_amount", "interest_rate", "term_months", "submitted_by_id", "submitted_by_name", "failure_reason", "cover_note", "penalty_capitalized", "simulated", "validated_at", "goal", "approval_type", "gds", "tds", "ltv", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/submissions/{id}/decisions": { "get": { "operationId": "listSubmissionDecisions", "summary": "List decisions on a submission", "description": "What the lender answered, newest first. A lender can revise a decision, so the highest `sequence` is the current one.", "tags": [ "Submissions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "decision", "description": "The type of this record. Always `decision`.", "type": "string", "enum": [ "decision" ] }, "id": { "type": "string", "description": "Stable identifier for the decision." }, "submission_id": { "type": "string", "description": "The submission this answers." }, "deal_id": { "type": "string", "description": "The deal it belongs to." }, "status_code": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Lender status code. See `status_label` for the readable form." }, "status_label": { "type": "string", "description": "What the status code means, in words." }, "decided_at": { "type": "string", "description": "When the lender made the decision." }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Lenders can revise a decision. Higher is newer." }, "lender_ref_number": { "nullable": true, "description": "The lender's own reference for this answer.", "type": "string" }, "note": { "nullable": true, "description": "Free-text note from the lender, when they send one.", "type": "string" }, "acknowledged_at": { "nullable": true, "description": "When a broker acknowledged it. Null if nobody has.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the decision." } }, "required": [ "object", "id", "submission_id", "deal_id", "status_code", "status_label", "decided_at", "sequence", "lender_ref_number", "note", "acknowledged_at", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications": { "get": { "operationId": "listCommunications", "summary": "List communications", "description": "Email, calls and messages, newest first, including mail that is not filed on a deal. `updated_since` pages on `updated_at`, which moves when a message is read, starred, filed on a deal or moved between folders. Subscribe to `email.received` to be told about new mail instead of polling for it.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "sms", "in_app", "portal", "call", "meeting" ] }, "description": "Filter by channel." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "description": "`inbound` or `outbound`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only communications on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only communications this contact sent." }, { "name": "thread_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only messages in this conversation, oldest first when paired with `updated_since`." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only mail sitting in this folder, by role (`inbox`, `sent`) or by the provider's own name." }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`true` for mail nobody has opened yet, `false` for mail that has been read." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}": { "get": { "operationId": "getCommunication", "summary": "Retrieve a communication", "description": "A single communication by id, with its body.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCommunication", "summary": "Update a conversation", "description": "The actions of the inbox: mark read or unread, mark done, star, set a reminder, or file the mail on a deal. Each change applies to every message in the conversation of this message, as in the inbox. Nothing goes to the client. The response is this message after the change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "description": "`true` marks every message in the conversation read, `false` marks it unread. BrokerPlus also changes it in the broker's own mailbox.", "type": "boolean" }, "done": { "description": "`true` marks the conversation done, which takes it out of the inbox. `false` puts it back.", "type": "boolean" }, "starred": { "description": "Star or unstar the conversation.", "type": "boolean" }, "remind_at": { "description": "ISO 8601 date-time in the future. The conversation comes back to the top of the broker's inbox at that time, and the broker gets a notification. Send `null` to clear the reminder.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "remind_condition": { "description": "With `remind_at`. `if_no_reply` cancels the reminder when the client replies first. Defaults to `always`.", "type": "string", "enum": [ "always", "if_no_reply" ] }, "deal_id": { "description": "File the mail on this deal. Send `null` to take it off its deal. Nothing goes to the client.", "nullable": true, "type": "string" }, "deal_scope": { "description": "With `deal_id`. `thread` files every message in the conversation, and `message` files only this one. Defaults to `thread`.", "type": "string", "enum": [ "thread", "message" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "No field to change, a `remind_at` in the past, or `remind_condition` or `deal_scope` without its field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "`deal_id` names no deal that you can reach (DEAL_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/attachments/{attachmentId}": { "get": { "operationId": "getCommunicationAttachment", "summary": "Get a link to an attachment", "description": "A signed link to one attached file, valid for five minutes. BrokerPlus fetches the file from the mail provider the first time anybody asks for it, so the first call on an old message is slower than the rest. If the mailbox no longer holds the message, the response is `410 ATTACHMENT_UNAVAILABLE`.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." }, "download_url": { "type": "string", "description": "A link to the file. It carries its own authorization, so do not store it." }, "download_url_expires_at": { "type": "string", "description": "When the link stops working." } }, "required": [ "object", "id", "name", "content_type", "size", "inline", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/snippets": { "get": { "operationId": "listSnippets", "summary": "List snippets", "description": "The saved replies of the broker your key acts as, by shortcut. The broker types a snippet's shortcut in the composer to insert it. Another broker's snippets are never listed.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "snippet", "description": "The type of this record. Always `snippet`.", "type": "string", "enum": [ "snippet" ] }, "id": { "type": "string", "description": "Stable identifier for the snippet." }, "shortcut": { "type": "string", "description": "What the broker types in the composer to insert it. Unique among the broker's snippets." }, "name": { "type": "string", "description": "The label the broker sees in the snippet list." }, "body": { "type": "string", "description": "The plain-text reply. Empty when the snippet is only files." }, "body_html": { "nullable": true, "description": "The same reply with formatting, as sanitized HTML. Null when it has none.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." } }, "required": [ "object", "id", "name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the reply carries, oldest first. They go out with the mail the snippet is inserted into." }, "created_at": { "type": "string", "description": "When the snippet was made." }, "updated_at": { "type": "string", "description": "Last change to the snippet. Use it with `updated_since`." } }, "required": [ "object", "id", "shortcut", "name", "body", "body_html", "attachments", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createSnippet", "summary": "Create a snippet", "description": "Saves a reply for the broker your key acts as, as the snippet manager in the inbox does. Nothing is sent: the broker inserts it into mail they write.", "tags": [ "Communications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shortcut": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$", "description": "What the broker types to insert it: 1 to 40 letters, digits, `_` or `-`. Unique among their snippets." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The label in the snippet list, 80 characters or fewer." }, "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "The plain-text reply, 10,000 characters or fewer." }, "body_html": { "nullable": true, "description": "The reply with formatting, as HTML. Unsafe HTML is removed, as from an email template. Send null to keep only the plain text.", "type": "string", "maxLength": 50000 } }, "required": [ "shortcut", "name", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "snippet", "description": "The type of this record. Always `snippet`.", "type": "string", "enum": [ "snippet" ] }, "id": { "type": "string", "description": "Stable identifier for the snippet." }, "shortcut": { "type": "string", "description": "What the broker types in the composer to insert it. Unique among the broker's snippets." }, "name": { "type": "string", "description": "The label the broker sees in the snippet list." }, "body": { "type": "string", "description": "The plain-text reply. Empty when the snippet is only files." }, "body_html": { "nullable": true, "description": "The same reply with formatting, as sanitized HTML. Null when it has none.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." } }, "required": [ "object", "id", "name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the reply carries, oldest first. They go out with the mail the snippet is inserted into." }, "created_at": { "type": "string", "description": "When the snippet was made." }, "updated_at": { "type": "string", "description": "Last change to the snippet. Use it with `updated_since`." } }, "required": [ "object", "id", "shortcut", "name", "body", "body_html", "attachments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as has no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker already has a snippet with this shortcut (DUPLICATE_SHORTCUT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/snippets/{id}": { "get": { "operationId": "getSnippet", "summary": "Retrieve a snippet", "description": "One saved reply of the broker your key acts as.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "snippet", "description": "The type of this record. Always `snippet`.", "type": "string", "enum": [ "snippet" ] }, "id": { "type": "string", "description": "Stable identifier for the snippet." }, "shortcut": { "type": "string", "description": "What the broker types in the composer to insert it. Unique among the broker's snippets." }, "name": { "type": "string", "description": "The label the broker sees in the snippet list." }, "body": { "type": "string", "description": "The plain-text reply. Empty when the snippet is only files." }, "body_html": { "nullable": true, "description": "The same reply with formatting, as sanitized HTML. Null when it has none.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." } }, "required": [ "object", "id", "name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the reply carries, oldest first. They go out with the mail the snippet is inserted into." }, "created_at": { "type": "string", "description": "When the snippet was made." }, "updated_at": { "type": "string", "description": "Last change to the snippet. Use it with `updated_since`." } }, "required": [ "object", "id", "shortcut", "name", "body", "body_html", "attachments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateSnippet", "summary": "Update a snippet", "description": "Changes the shortcut, name or words of a snippet. Only the fields you send change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shortcut": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$", "description": "What the broker types to insert it: 1 to 40 letters, digits, `_` or `-`. Unique among their snippets." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The label in the snippet list, 80 characters or fewer." }, "body": { "description": "The new plain-text reply.", "type": "string", "minLength": 1, "maxLength": 10000 }, "body_html": { "nullable": true, "description": "The reply with formatting, as HTML. Unsafe HTML is removed, as from an email template. Send null to keep only the plain text.", "type": "string", "maxLength": 50000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "snippet", "description": "The type of this record. Always `snippet`.", "type": "string", "enum": [ "snippet" ] }, "id": { "type": "string", "description": "Stable identifier for the snippet." }, "shortcut": { "type": "string", "description": "What the broker types in the composer to insert it. Unique among the broker's snippets." }, "name": { "type": "string", "description": "The label the broker sees in the snippet list." }, "body": { "type": "string", "description": "The plain-text reply. Empty when the snippet is only files." }, "body_html": { "nullable": true, "description": "The same reply with formatting, as sanitized HTML. Null when it has none.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." } }, "required": [ "object", "id", "name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the reply carries, oldest first. They go out with the mail the snippet is inserted into." }, "created_at": { "type": "string", "description": "When the snippet was made." }, "updated_at": { "type": "string", "description": "Last change to the snippet. Use it with `updated_since`." } }, "required": [ "object", "id", "shortcut", "name", "body", "body_html", "attachments", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The broker has no snippet with this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker already has a snippet with this shortcut (DUPLICATE_SHORTCUT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteSnippet", "summary": "Delete a snippet", "description": "Deletes the snippet and its files. You cannot undo this. Mail it was already inserted into keeps its words.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The broker has no snippet with this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/snippets/{id}/attachments": { "post": { "operationId": "attachSnippetFile", "summary": "Attach a file to a snippet", "description": "Adds a file that goes out with the mail the snippet is inserted into. Send it as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. BrokerPlus reads the type from the content, not the name: a PDF, image, Word or Excel file is stored as what it is, and content with no recognisable type is taken only as CSV. A snippet holds up to 10 files. Nothing is sent.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "The file: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV, at most 25 MB. Its file name is the name the broker sees." } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The file name the broker sees, with its extension. A CSV file's name must end in `.csv`." }, "content_base64": { "type": "string", "minLength": 1, "description": "The file, in standard base64: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV, at most 25 MB. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." } }, "required": [ "object", "id", "name", "content_type", "size" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing or empty (NO_FILE), is not an allowed type (INVALID_TYPE), is larger than 25 MB (FILE_TOO_LARGE), the snippet already holds 10 files (TOO_MANY_ATTACHMENTS), or the base64 is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The broker has no snippet with this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/snippets/{id}/attachments/{attachmentId}": { "delete": { "operationId": "removeSnippetFile", "summary": "Remove a file from a snippet", "description": "Takes the file off the snippet and deletes it. Mail already sent with it keeps its copy.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The snippet has no file with this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "get": { "operationId": "getSnippetAttachment", "summary": "Get a link to a snippet's file", "description": "A signed link to one file of a snippet, valid for five minutes.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "snippet_attachment", "description": "The type of this record. Always `snippet_attachment`.", "type": "string", "enum": [ "snippet_attachment" ] }, "id": { "type": "string", "description": "Identifier for this file on this snippet. Use it to get a download link." }, "name": { "type": "string", "description": "Filename, as the broker attached it." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "download_url": { "type": "string", "description": "A link to the file. It carries its own authorization, so do not store it." }, "download_url_expires_at": { "type": "string", "description": "When the link stops working." } }, "required": [ "object", "id", "name", "content_type", "size", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/folders": { "post": { "operationId": "fileCommunication", "summary": "File a conversation in a folder", "description": "Files every message in the conversation of this message into a folder of the mailbox that holds it, as filing does in the inbox. The move also happens in the broker's own mail app, a few seconds later. On Gmail a conversation can sit in several labels; on Outlook it moves to the one folder. Nothing goes to the client. The response is this message after the change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "string", "minLength": 1, "description": "A folder id from `GET /v1/communication-folders`, in the mailbox that holds the message." } }, "required": [ "folder_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "An Outlook or IMAP message can only be in one folder (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in, or its mailbox has no such folder (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The message is a call or a text, not mail in a connected mailbox (NOT_IN_A_MAILBOX).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The mailbox is disconnected, so the move cannot reach it (MAILBOX_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/folders/{folderId}": { "delete": { "operationId": "unfileCommunication", "summary": "Take a conversation out of a folder", "description": "Takes every message in the conversation of this message out of a folder of its mailbox. On Gmail this removes the label. Taking a conversation out of a folder it is not in changes nothing. The response is this message after the change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in, or its mailbox has no such folder (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The message is a call or a text, not mail in a connected mailbox (NOT_IN_A_MAILBOX).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The mailbox is disconnected, so the move cannot reach it (MAILBOX_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communication-folders": { "get": { "operationId": "listCommunicationFolders", "summary": "List mail folders", "description": "The folders and labels of one connected mailbox, by name. Without `mailbox` this is the broker's own mailbox, or the team's shared one when the broker has none, the same tree the inbox shows. With no mailbox connected, the list is empty. Folders are made and renamed in the mail app; BrokerPlus reads them from there.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "mailbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The address of a connected mailbox that the broker can read, as `mailbox` on a communication shows it." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/folders`." }, "mailbox": { "nullable": true, "description": "The address of the connected mailbox the folder belongs to.", "type": "string" }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it. On Gmail a nested label is one name with a separator, such as `Clients/Active`." }, "parent_id": { "nullable": true, "description": "The folder it sits inside, on a mailbox that nests folders. Null at the top.", "type": "string" }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`. Null for a folder the broker made.", "type": "string" }, "is_system": { "type": "boolean", "description": "True for a folder the mail provider made, such as Inbox or Sent." }, "created_at": { "type": "string", "description": "When BrokerPlus first saw the folder." }, "updated_at": { "type": "string", "description": "Last change BrokerPlus recorded to the folder. Use it with `updated_since`." } }, "required": [ "object", "id", "mailbox", "name", "parent_id", "role", "is_system", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No connected mailbox the broker can read has this address (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communication-folders/{id}": { "get": { "operationId": "getCommunicationFolder", "summary": "Retrieve a mail folder", "description": "One folder or label of a connected mailbox that the broker can read.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/folders`." }, "mailbox": { "nullable": true, "description": "The address of the connected mailbox the folder belongs to.", "type": "string" }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it. On Gmail a nested label is one name with a separator, such as `Clients/Active`." }, "parent_id": { "nullable": true, "description": "The folder it sits inside, on a mailbox that nests folders. Null at the top.", "type": "string" }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`. Null for a folder the broker made.", "type": "string" }, "is_system": { "type": "boolean", "description": "True for a folder the mail provider made, such as Inbox or Sent." }, "created_at": { "type": "string", "description": "When BrokerPlus first saw the folder." }, "updated_at": { "type": "string", "description": "Last change BrokerPlus recorded to the folder. Use it with `updated_since`." } }, "required": [ "object", "id", "mailbox", "name", "parent_id", "role", "is_system", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/tags": { "post": { "operationId": "tagCommunication", "summary": "Put a tag on a conversation", "description": "Puts an inbox tag on every message in the conversation of this message, as in the inbox. Putting on a tag the conversation already has changes nothing. On an Outlook mailbox the tag is also written to Outlook as a category. Nothing goes to the client. The response is this message after the change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "string", "minLength": 1, "description": "A tag id from `GET /v1/communication-tags`." } }, "required": [ "tag_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in, or the tag does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The conversation is in a Gmail mailbox, whose labels BrokerPlus does not change (TAG_SYNC_UNSUPPORTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The mailbox is disconnected, so the change cannot reach it (MAILBOX_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/tags/{tagId}": { "delete": { "operationId": "untagCommunication", "summary": "Take a tag off a conversation", "description": "Takes an inbox tag off every message in the conversation of this message. Taking off a tag that is not there changes nothing. The response is this message after the change.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication", "description": "The type of this record. Always `communication`.", "type": "string", "enum": [ "communication" ] }, "id": { "type": "string", "description": "Stable identifier." }, "deal_id": { "nullable": true, "description": "The deal it is filed under, when it names one.", "type": "string" }, "channel": { "type": "string", "description": "How it happened, e.g. `email`, `sms`, `call`." }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "subject": { "nullable": true, "description": "Subject line, for channels that have one.", "type": "string" }, "body": { "type": "string", "description": "Plain-text body. Call transcripts appear here too." }, "body_html": { "nullable": true, "description": "The HTML the sender wrote, exactly as it arrived and never sanitized. Null for a message that had no HTML part. Sanitize it before rendering it anywhere.", "type": "string" }, "status": { "type": "string", "description": "Delivery state, e.g. `sent`." }, "from": { "nullable": true, "description": "Who it came from. Null on a channel that carries no address.", "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone it was addressed to. Empty on a channel with no addresses." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "name": { "nullable": true, "description": "Display name the mail provider gave, when it gave one.", "type": "string" }, "email": { "type": "string", "description": "The address." } }, "required": [ "name", "email" ], "additionalProperties": false }, "description": "Everyone copied on it." }, "from_contact_id": { "nullable": true, "description": "The contact who sent it, when the sender is known to you.", "type": "string" }, "from_user_id": { "nullable": true, "description": "The broker who sent it, for outbound.", "type": "string" }, "to_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts it was sent to, when BrokerPlus sent it. Empty on mail that came in, and on mail sent outside BrokerPlus." }, "mailbox": { "nullable": true, "description": "The connected mailbox this sits in. Null for a message that arrived outside a mailbox.", "type": "string" }, "mailbox_user_id": { "nullable": true, "description": "The broker whose mailbox or phone line it sits in. Null when it belongs to nobody in particular, such as a shared inbox.", "type": "string" }, "done_at": { "nullable": true, "description": "When a broker marked it done in the inbox. Null while it is still open.", "type": "string" }, "remind_at": { "nullable": true, "description": "When the inbox brings it back to the broker as a reminder. Null when no reminder is set.", "type": "string" }, "thread_id": { "nullable": true, "description": "Groups a conversation. Stable across replies.", "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "attachment", "description": "The type of this record. Always `attachment`.", "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "description": "Identifier for this attachment on this message. Use it to get a download link." }, "name": { "type": "string", "description": "Filename as the sender attached it." }, "content_type": { "nullable": true, "description": "MIME type the provider reported, when it reported one.", "type": "string" }, "size": { "nullable": true, "description": "Size in bytes, when the provider reported one.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inline": { "type": "boolean", "description": "True for an image embedded in the body rather than attached to it." } }, "required": [ "object", "id", "name", "content_type", "size", "inline" ], "additionalProperties": false }, "description": "What was attached. Empty when nothing was." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_folder", "description": "The type of this record. Always `communication_folder`.", "type": "string", "enum": [ "communication_folder" ] }, "id": { "type": "string", "description": "The folder. Resolve it against `GET /v1/communication-folders`." }, "name": { "type": "string", "description": "The folder or label exactly as the mail provider names it." }, "role": { "nullable": true, "description": "Normalized role: `inbox`, `sent`, `archive`, `drafts`, `trash`, `spam`, or `unknown`.", "type": "string" } }, "required": [ "object", "id", "name", "role" ], "additionalProperties": false }, "description": "The folders and labels it sits in, as the mail provider reports them." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "The tag. Resolve it against `GET /v1/communication-tags`." }, "name": { "type": "string", "description": "The tag's name, for display." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI. Cosmetic." } }, "required": [ "object", "id", "name", "color" ], "additionalProperties": false }, "description": "The inbox tags on it. A tag is put on every message of a conversation at once. Change them with `POST /v1/communications/{id}/tags` and `DELETE /v1/communications/{id}/tags/{tagId}`." }, "read_at": { "nullable": true, "description": "When it was read in the mail app. Null means unread. Mail that predates the BrokerPlus connection is recorded as already read.", "type": "string" }, "starred": { "type": "boolean", "description": "Whether it is starred or flagged in the mail app." }, "sent_at": { "nullable": true, "description": "When it was sent.", "type": "string" }, "received_at": { "nullable": true, "description": "When it arrived.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded it." }, "updated_at": { "type": "string", "description": "Last change to a field on this record, its folders included. Reading, starring, filing on a deal and moving between folders change it. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "channel", "direction", "subject", "body", "body_html", "status", "from", "to", "cc", "from_contact_id", "from_user_id", "to_contact_ids", "mailbox", "mailbox_user_id", "done_at", "remind_at", "thread_id", "attachments", "folders", "tags", "read_at", "starred", "sent_at", "received_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in, or the tag does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The conversation is in a Gmail mailbox, whose labels BrokerPlus does not change (TAG_SYNC_UNSUPPORTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The mailbox is disconnected, so the change cannot reach it (MAILBOX_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communication-tags": { "get": { "operationId": "listCommunicationTags", "summary": "List inbox tags", "description": "The brokerage's inbox tags, in display order. A broker puts them on conversations in the inbox. Contact tags and deal tags are separate lists.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/tags`." }, "name": { "type": "string", "description": "The label brokers see in the inbox. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "color", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCommunicationTag", "summary": "Create an inbox tag", "description": "Adds a tag to the brokerage's inbox tags. The new tag goes to the end of the order. A name that an archived tag had restores that tag.", "tags": [ "Communications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/tags`." }, "name": { "type": "string", "description": "The label brokers see in the inbox. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "color", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The name is empty or longer than 40 characters, or the colour is not in the palette (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A live inbox tag has this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communication-tags/{id}": { "get": { "operationId": "getCommunicationTag", "summary": "Retrieve an inbox tag", "description": "One inbox tag.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/tags`." }, "name": { "type": "string", "description": "The label brokers see in the inbox. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "color", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCommunicationTag", "summary": "Update an inbox tag", "description": "Changes the name or colour of an inbox tag. Every conversation that has the tag keeps it.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind." }, "color": { "type": "string", "description": "The swatch: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`. Cosmetic." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "communication_tag", "description": "The type of this record. Always `communication_tag`.", "type": "string", "enum": [ "communication_tag" ] }, "id": { "type": "string", "description": "Stable identifier. Pass it to `POST /v1/communications/{id}/tags`." }, "name": { "type": "string", "description": "The label brokers see in the inbox. Unique within the brokerage." }, "color": { "type": "string", "description": "Swatch name used in the BrokerPlus UI, e.g. `navy`. Cosmetic." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Display order, ascending." }, "created_at": { "type": "string", "description": "When the tag was created." }, "updated_at": { "type": "string", "description": "Last change to the tag's name, colour or order. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "color", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live inbox tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another inbox tag has this name (DUPLICATE), or the tag came from a mailbox and is on synced mail, so its name cannot change (TAG_IN_USE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "archiveCommunicationTag", "summary": "Archive an inbox tag", "description": "Removes the tag from the list and from every conversation that has it, as Delete does in the inbox. To restore the name, create a tag with the same name. The conversations do not get the tag back.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live inbox tag in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The tag came from a mailbox and is on synced mail (TAG_IN_USE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/batch": { "post": { "operationId": "batchWriteContacts", "summary": "Create or update contacts in a batch", "description": "Creates or updates up to 100 contacts in one request. Each item is the body of `POST /v1/contacts` for a new contact, or of `PATCH /v1/contacts/{id}` for a contact that exists. Send `external_id` with `namespace`, and the next batch with that id updates the same contact. The items are not one transaction: an item that fails does not stop the others. Each item counts as one request against the rate limit. Refer to [Migrate from another CRM](/migrate-from-a-crm).", "tags": [ "Contacts" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "description": "The name of the system that your `external_id` values come from, for example `zoho`. It is not case-sensitive. It is necessary when an item has an `external_id`. Two systems can then use the same id without a conflict.", "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_.-]+$" }, "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The BrokerPlus id of a record to update. Omit it to create a record, or to match on `external_id`.", "type": "string" }, "external_id": { "description": "Your id for the record. The first time, BrokerPlus creates the record and keeps this id with it. The next time, BrokerPlus updates that record.", "type": "string", "minLength": 1, "maxLength": 200 }, "data": { "type": "object", "additionalProperties": {}, "description": "The fields. For a new record, send what the single create takes. For a record that exists, send what the single update takes. The single endpoint checks them." } }, "required": [ "data" ], "additionalProperties": false }, "description": "From 1 to 100 records. BrokerPlus writes them in this order." } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items created a record." }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items updated a record." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items failed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "batch_item_result", "description": "The type of this record. Always `batch_item_result`.", "type": "string", "enum": [ "batch_item_result" ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the item in `items`, from 0." }, "status": { "type": "string", "enum": [ "created", "updated", "failed" ], "description": "What happened to this item. A failed item does not stop the items after it." }, "id": { "nullable": true, "description": "The BrokerPlus id of the record. Null when the item failed before a record was found.", "type": "string" }, "external_id": { "nullable": true, "description": "The `external_id` that you sent. Null when you sent none.", "type": "string" }, "error": { "nullable": true, "description": "Why the item failed, as the single endpoint says it. Null when it did not fail.", "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status that the single endpoint returned for this item." }, "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "status", "code", "message" ], "additionalProperties": false } }, "required": [ "object", "index", "status", "id", "external_id", "error" ], "additionalProperties": false }, "description": "One result for each item, in the order of `items`." } }, "required": [ "created", "updated", "failed", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The batch is not valid: no items, more than 100, an `external_id` without `namespace`, or the same `external_id` two times. Nothing was written (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/leads/batch": { "post": { "operationId": "batchWriteLeads", "summary": "Create or update leads in a batch", "description": "Creates or updates up to 100 leads in one request. Each item is the body of `POST /v1/leads` for a new lead, or of `PATCH /v1/leads/{id}` for a lead that exists. Send `external_id` with `namespace`, and the next batch with that id updates the same lead. The items are not one transaction: an item that fails does not stop the others. Each item counts as one request against the rate limit. Refer to [Migrate from another CRM](/migrate-from-a-crm).", "tags": [ "Leads" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "description": "The name of the system that your `external_id` values come from, for example `zoho`. It is not case-sensitive. It is necessary when an item has an `external_id`. Two systems can then use the same id without a conflict.", "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_.-]+$" }, "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The BrokerPlus id of a record to update. Omit it to create a record, or to match on `external_id`.", "type": "string" }, "external_id": { "description": "Your id for the record. The first time, BrokerPlus creates the record and keeps this id with it. The next time, BrokerPlus updates that record.", "type": "string", "minLength": 1, "maxLength": 200 }, "data": { "type": "object", "additionalProperties": {}, "description": "The fields. For a new record, send what the single create takes. For a record that exists, send what the single update takes. The single endpoint checks them." } }, "required": [ "data" ], "additionalProperties": false }, "description": "From 1 to 100 records. BrokerPlus writes them in this order." } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items created a record." }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items updated a record." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items failed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "batch_item_result", "description": "The type of this record. Always `batch_item_result`.", "type": "string", "enum": [ "batch_item_result" ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the item in `items`, from 0." }, "status": { "type": "string", "enum": [ "created", "updated", "failed" ], "description": "What happened to this item. A failed item does not stop the items after it." }, "id": { "nullable": true, "description": "The BrokerPlus id of the record. Null when the item failed before a record was found.", "type": "string" }, "external_id": { "nullable": true, "description": "The `external_id` that you sent. Null when you sent none.", "type": "string" }, "error": { "nullable": true, "description": "Why the item failed, as the single endpoint says it. Null when it did not fail.", "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status that the single endpoint returned for this item." }, "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "status", "code", "message" ], "additionalProperties": false } }, "required": [ "object", "index", "status", "id", "external_id", "error" ], "additionalProperties": false }, "description": "One result for each item, in the order of `items`." } }, "required": [ "created", "updated", "failed", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The batch is not valid: no items, more than 100, an `external_id` without `namespace`, or the same `external_id` two times. Nothing was written (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/batch": { "post": { "operationId": "batchWriteDeals", "summary": "Create or update deals in a batch", "description": "Creates or updates up to 100 deals in one request. Each item is the body of `POST /v1/deals` for a new deal, or of `PATCH /v1/deals/{id}` for a deal that exists. Send `external_id` with `namespace`, and the next batch with that id updates the same deal. The items are not one transaction: an item that fails does not stop the others. Each item counts as one request against the rate limit. Refer to [Migrate from another CRM](/migrate-from-a-crm).", "tags": [ "Deals" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "description": "The name of the system that your `external_id` values come from, for example `zoho`. It is not case-sensitive. It is necessary when an item has an `external_id`. Two systems can then use the same id without a conflict.", "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_.-]+$" }, "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The BrokerPlus id of a record to update. Omit it to create a record, or to match on `external_id`.", "type": "string" }, "external_id": { "description": "Your id for the record. The first time, BrokerPlus creates the record and keeps this id with it. The next time, BrokerPlus updates that record.", "type": "string", "minLength": 1, "maxLength": 200 }, "data": { "type": "object", "additionalProperties": {}, "description": "The fields. For a new record, send what the single create takes. For a record that exists, send what the single update takes. The single endpoint checks them." } }, "required": [ "data" ], "additionalProperties": false }, "description": "From 1 to 100 records. BrokerPlus writes them in this order." } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items created a record." }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items updated a record." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items failed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "batch_item_result", "description": "The type of this record. Always `batch_item_result`.", "type": "string", "enum": [ "batch_item_result" ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the item in `items`, from 0." }, "status": { "type": "string", "enum": [ "created", "updated", "failed" ], "description": "What happened to this item. A failed item does not stop the items after it." }, "id": { "nullable": true, "description": "The BrokerPlus id of the record. Null when the item failed before a record was found.", "type": "string" }, "external_id": { "nullable": true, "description": "The `external_id` that you sent. Null when you sent none.", "type": "string" }, "error": { "nullable": true, "description": "Why the item failed, as the single endpoint says it. Null when it did not fail.", "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status that the single endpoint returned for this item." }, "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "status", "code", "message" ], "additionalProperties": false } }, "required": [ "object", "index", "status", "id", "external_id", "error" ], "additionalProperties": false }, "description": "One result for each item, in the order of `items`." } }, "required": [ "created", "updated", "failed", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The batch is not valid: no items, more than 100, an `external_id` without `namespace`, or the same `external_id` two times. Nothing was written (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/batch": { "post": { "operationId": "batchWriteTasks", "summary": "Create or update tasks in a batch", "description": "Creates or updates up to 100 tasks in one request. Each item is the body of `POST /v1/tasks` for a new task, or of `PATCH /v1/tasks/{id}` for a task that exists. Send `external_id` with `namespace`, and the next batch with that id updates the same task. The items are not one transaction: an item that fails does not stop the others. Each item counts as one request against the rate limit. Refer to [Migrate from another CRM](/migrate-from-a-crm).", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "namespace": { "description": "The name of the system that your `external_id` values come from, for example `zoho`. It is not case-sensitive. It is necessary when an item has an `external_id`. Two systems can then use the same id without a conflict.", "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_.-]+$" }, "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The BrokerPlus id of a record to update. Omit it to create a record, or to match on `external_id`.", "type": "string" }, "external_id": { "description": "Your id for the record. The first time, BrokerPlus creates the record and keeps this id with it. The next time, BrokerPlus updates that record.", "type": "string", "minLength": 1, "maxLength": 200 }, "data": { "type": "object", "additionalProperties": {}, "description": "The fields. For a new record, send what the single create takes. For a record that exists, send what the single update takes. The single endpoint checks them." } }, "required": [ "data" ], "additionalProperties": false }, "description": "From 1 to 100 records. BrokerPlus writes them in this order." } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items created a record." }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items updated a record." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items failed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "batch_item_result", "description": "The type of this record. Always `batch_item_result`.", "type": "string", "enum": [ "batch_item_result" ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the item in `items`, from 0." }, "status": { "type": "string", "enum": [ "created", "updated", "failed" ], "description": "What happened to this item. A failed item does not stop the items after it." }, "id": { "nullable": true, "description": "The BrokerPlus id of the record. Null when the item failed before a record was found.", "type": "string" }, "external_id": { "nullable": true, "description": "The `external_id` that you sent. Null when you sent none.", "type": "string" }, "error": { "nullable": true, "description": "Why the item failed, as the single endpoint says it. Null when it did not fail.", "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status that the single endpoint returned for this item." }, "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "status", "code", "message" ], "additionalProperties": false } }, "required": [ "object", "index", "status", "id", "external_id", "error" ], "additionalProperties": false }, "description": "One result for each item, in the order of `items`." } }, "required": [ "created", "updated", "failed", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The batch is not valid: no items, more than 100, an `external_id` without `namespace`, or the same `external_id` two times. Nothing was written (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/calls": { "get": { "operationId": "listCalls", "summary": "List calls", "description": "The call log, newest first: calls on BrokerPlus lines, on a connected phone service, and calls that an integration logged. Each call has its transcript and recap when it has them. Subscribe to `call.logged` to know about new calls without a poll.", "tags": [ "Calls" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "description": "`inbound` or `outbound`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only calls on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only calls with this contact." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "call", "description": "The type of this record. Always `call`.", "type": "string", "enum": [ "call" ] }, "id": { "type": "string", "description": "Stable identifier. The same id reads the call as a communication." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` when the client called, `outbound` when the broker did." }, "status": { "type": "string", "description": "How the call ended: `completed`, `missed`, or `voicemail`. A live call can show `ringing`." }, "contact_id": { "nullable": true, "description": "The contact on the other end. Null when nobody in the book matches.", "type": "string" }, "contact_name": { "nullable": true, "description": "The contact's name, for display. Null with `contact_id`.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the call is filed on. Null when it is on no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display. Null with `deal_id`.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose call log holds the call. Null for a brokerage line that nobody owns.", "type": "string" }, "from": { "nullable": true, "description": "The number that made the call, as recorded. Null when it is not known.", "type": "string" }, "to": { "nullable": true, "description": "The number that took the call, as recorded. Null when it is not known.", "type": "string" }, "started_at": { "type": "string", "description": "When the call started." }, "duration_seconds": { "nullable": true, "description": "How long the call lasted, in seconds. Null when not known.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "provider": { "type": "string", "description": "The phone system that recorded the call: `brokerplus`, `dialpad`, `quo`, `upload` for a pasted transcript, or the `provider` an integration sent." }, "external_id": { "nullable": true, "description": "The call's id in the provider, when an integration sent one with `POST /v1/calls`.", "type": "string" }, "recording_url": { "nullable": true, "description": "The link to the recording that an integration sent. BrokerPlus does not copy or check this file.", "type": "string" }, "has_recording": { "type": "boolean", "description": "True when BrokerPlus keeps the audio of the call itself." }, "transcript": { "nullable": true, "description": "The words of the call as plain text. Null when there is no transcript.", "type": "string" }, "transcript_segments": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "minimum": 0, "description": "Where the turn starts, in seconds from the start of the call." }, "end_seconds": { "type": "number", "minimum": 0, "description": "Where the turn ends, in seconds from the start of the call." }, "speaker": { "type": "string", "enum": [ "broker", "client" ], "description": "Who speaks: `broker` for someone at the brokerage, `client` for the other party." }, "speaker_name": { "description": "The name of the speaker, when you know it.", "nullable": true, "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the speaker said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript turn by turn, when the phone system gave the turns. Empty when it did not." }, "summary": { "nullable": true, "description": "The recap of the call. BrokerPlus writes one from the transcript when the integration sent none.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the call." }, "updated_at": { "type": "string", "description": "Last change to the call. Use it with `updated_since`." } }, "required": [ "object", "id", "direction", "status", "contact_id", "contact_name", "deal_id", "deal_name", "user_id", "from", "to", "started_at", "duration_seconds", "provider", "external_id", "recording_url", "has_recording", "transcript", "transcript_segments", "summary", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "logCall", "summary": "Log a call", "description": "Puts a call from another phone system or recorder in the broker's call log. The call shows on the contact and the deal like a call made in BrokerPlus. Send a transcript, and BrokerPlus writes the recap and fills in the application from it, as it does for its own calls. Send `external_id` to make a retry safe: a call already logged with the same `provider` and `external_id` comes back with status `200`.", "tags": [ "Calls" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` when the client called, `outbound` when the broker did." }, "provider": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The phone system or recorder the call came from, for example `Dialpad`, `Plaud`, or `Grain`." }, "external_id": { "description": "The call's id in that system. Send it, and a second request with the same `provider` and `external_id` returns the call already logged instead of a copy.", "type": "string", "minLength": 1, "maxLength": 200 }, "started_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 timestamp. When the call started." }, "duration_seconds": { "description": "How long the call lasted, in seconds.", "type": "integer", "minimum": 0, "maximum": 86400 }, "status": { "description": "How the call ended. Defaults to `completed`.", "type": "string", "enum": [ "completed", "missed", "voicemail" ] }, "contact_id": { "description": "The contact on the other end. Omit it, and BrokerPlus finds the contact by the client's number. A number that matches more than one contact matches none.", "type": "string" }, "deal_id": { "description": "The deal to file the call on. Omit it, and BrokerPlus files the call on the contact's most recent deal.", "type": "string" }, "from": { "description": "The number that made the call. Any format.", "type": "string", "maxLength": 40 }, "to": { "description": "The number that took the call. Any format.", "type": "string", "maxLength": 40 }, "recording_url": { "description": "An `https` link to the recording. BrokerPlus keeps the link and shows it on the call. It does not copy the audio.", "type": "string", "maxLength": 2000, "format": "uri" }, "transcript": { "description": "The words of the call as plain text. Send this or `transcript_segments`.", "type": "string", "minLength": 1, "maxLength": 200000 }, "transcript_segments": { "description": "The transcript turn by turn. BrokerPlus makes the plain text from these when you send no `transcript`.", "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "minimum": 0, "description": "Where the turn starts, in seconds from the start of the call." }, "end_seconds": { "type": "number", "minimum": 0, "description": "Where the turn ends, in seconds from the start of the call." }, "speaker": { "type": "string", "enum": [ "broker", "client" ], "description": "Who speaks: `broker` for someone at the brokerage, `client` for the other party." }, "speaker_name": { "description": "The name of the speaker, when you know it.", "nullable": true, "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the speaker said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false } }, "summary": { "description": "Your recap of the call. Send it, and BrokerPlus keeps it and does not write its own. Omit it, and BrokerPlus writes a recap from the transcript, as it does for a call on its own lines.", "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "direction", "provider", "started_at" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call", "description": "The type of this record. Always `call`.", "type": "string", "enum": [ "call" ] }, "id": { "type": "string", "description": "Stable identifier. The same id reads the call as a communication." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` when the client called, `outbound` when the broker did." }, "status": { "type": "string", "description": "How the call ended: `completed`, `missed`, or `voicemail`. A live call can show `ringing`." }, "contact_id": { "nullable": true, "description": "The contact on the other end. Null when nobody in the book matches.", "type": "string" }, "contact_name": { "nullable": true, "description": "The contact's name, for display. Null with `contact_id`.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the call is filed on. Null when it is on no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display. Null with `deal_id`.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose call log holds the call. Null for a brokerage line that nobody owns.", "type": "string" }, "from": { "nullable": true, "description": "The number that made the call, as recorded. Null when it is not known.", "type": "string" }, "to": { "nullable": true, "description": "The number that took the call, as recorded. Null when it is not known.", "type": "string" }, "started_at": { "type": "string", "description": "When the call started." }, "duration_seconds": { "nullable": true, "description": "How long the call lasted, in seconds. Null when not known.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "provider": { "type": "string", "description": "The phone system that recorded the call: `brokerplus`, `dialpad`, `quo`, `upload` for a pasted transcript, or the `provider` an integration sent." }, "external_id": { "nullable": true, "description": "The call's id in the provider, when an integration sent one with `POST /v1/calls`.", "type": "string" }, "recording_url": { "nullable": true, "description": "The link to the recording that an integration sent. BrokerPlus does not copy or check this file.", "type": "string" }, "has_recording": { "type": "boolean", "description": "True when BrokerPlus keeps the audio of the call itself." }, "transcript": { "nullable": true, "description": "The words of the call as plain text. Null when there is no transcript.", "type": "string" }, "transcript_segments": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "minimum": 0, "description": "Where the turn starts, in seconds from the start of the call." }, "end_seconds": { "type": "number", "minimum": 0, "description": "Where the turn ends, in seconds from the start of the call." }, "speaker": { "type": "string", "enum": [ "broker", "client" ], "description": "Who speaks: `broker` for someone at the brokerage, `client` for the other party." }, "speaker_name": { "description": "The name of the speaker, when you know it.", "nullable": true, "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the speaker said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript turn by turn, when the phone system gave the turns. Empty when it did not." }, "summary": { "nullable": true, "description": "The recap of the call. BrokerPlus writes one from the transcript when the integration sent none.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the call." }, "updated_at": { "type": "string", "description": "Last change to the call. Use it with `updated_since`." } }, "required": [ "object", "id", "direction", "status", "contact_id", "contact_name", "deal_id", "deal_name", "user_id", "from", "to", "started_at", "duration_seconds", "provider", "external_id", "recording_url", "has_recording", "transcript", "transcript_segments", "summary", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid. `details` names each field to fix (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A call with this `provider` and `external_id` is in the call log of a broker whose calls this key cannot read (CALL_EXISTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/calls/{id}": { "get": { "operationId": "getCall", "summary": "Retrieve a call", "description": "A single call by id, with its transcript and recap.", "tags": [ "Calls" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call", "description": "The type of this record. Always `call`.", "type": "string", "enum": [ "call" ] }, "id": { "type": "string", "description": "Stable identifier. The same id reads the call as a communication." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` when the client called, `outbound` when the broker did." }, "status": { "type": "string", "description": "How the call ended: `completed`, `missed`, or `voicemail`. A live call can show `ringing`." }, "contact_id": { "nullable": true, "description": "The contact on the other end. Null when nobody in the book matches.", "type": "string" }, "contact_name": { "nullable": true, "description": "The contact's name, for display. Null with `contact_id`.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the call is filed on. Null when it is on no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display. Null with `deal_id`.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose call log holds the call. Null for a brokerage line that nobody owns.", "type": "string" }, "from": { "nullable": true, "description": "The number that made the call, as recorded. Null when it is not known.", "type": "string" }, "to": { "nullable": true, "description": "The number that took the call, as recorded. Null when it is not known.", "type": "string" }, "started_at": { "type": "string", "description": "When the call started." }, "duration_seconds": { "nullable": true, "description": "How long the call lasted, in seconds. Null when not known.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "provider": { "type": "string", "description": "The phone system that recorded the call: `brokerplus`, `dialpad`, `quo`, `upload` for a pasted transcript, or the `provider` an integration sent." }, "external_id": { "nullable": true, "description": "The call's id in the provider, when an integration sent one with `POST /v1/calls`.", "type": "string" }, "recording_url": { "nullable": true, "description": "The link to the recording that an integration sent. BrokerPlus does not copy or check this file.", "type": "string" }, "has_recording": { "type": "boolean", "description": "True when BrokerPlus keeps the audio of the call itself." }, "transcript": { "nullable": true, "description": "The words of the call as plain text. Null when there is no transcript.", "type": "string" }, "transcript_segments": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "minimum": 0, "description": "Where the turn starts, in seconds from the start of the call." }, "end_seconds": { "type": "number", "minimum": 0, "description": "Where the turn ends, in seconds from the start of the call." }, "speaker": { "type": "string", "enum": [ "broker", "client" ], "description": "Who speaks: `broker` for someone at the brokerage, `client` for the other party." }, "speaker_name": { "description": "The name of the speaker, when you know it.", "nullable": true, "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the speaker said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript turn by turn, when the phone system gave the turns. Empty when it did not." }, "summary": { "nullable": true, "description": "The recap of the call. BrokerPlus writes one from the transcript when the integration sent none.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus recorded the call." }, "updated_at": { "type": "string", "description": "Last change to the call. Use it with `updated_since`." } }, "required": [ "object", "id", "direction", "status", "contact_id", "contact_name", "deal_id", "deal_name", "user_id", "from", "to", "started_at", "duration_seconds", "provider", "external_id", "recording_url", "has_recording", "transcript", "transcript_segments", "summary", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meetings": { "get": { "operationId": "listMeetings", "summary": "List recorded meetings", "description": "The video meetings BrokerPlus took notes in, as the Meetings tab lists them, with BrokerPlus's summary. Newest first, or oldest first with `updated_since`. Read the transcript with `GET /v1/meetings/{id}`. The recording itself is not on the API.", "tags": [ "Communications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only meetings filed on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only meetings with this client." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "meeting", "description": "The type of this record. Always `meeting`.", "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting. It is also its id in `GET /v1/communications`." }, "title": { "nullable": true, "description": "The meeting's title on the video platform. Null when the platform gave none.", "type": "string" }, "provider": { "nullable": true, "description": "What recorded it: `recall` for the BrokerPlus notetaker in a Zoom, Google Meet or Teams call, `roam` for a Roam meeting. Null before a recording arrives.", "type": "string" }, "status": { "type": "string", "description": "Where the meeting is, as the Meetings tab shows it." }, "deal_id": { "nullable": true, "description": "The deal the meeting is filed on. Null when it is on none.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the meeting is with. Null when nobody is matched.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose meeting it is. Resolve with `GET /v1/users`.", "type": "string" }, "started_at": { "nullable": true, "description": "When the recording started. Null before it starts.", "type": "string" }, "ended_at": { "nullable": true, "description": "When the recording ended. Null while it runs.", "type": "string" }, "duration_seconds": { "nullable": true, "description": "How long it was recorded, in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended_reason": { "nullable": true, "description": "Why the recording ended, as the platform said, such as `timeout_exceeded_everyone_left`.", "type": "string" }, "participant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people were in the meeting." }, "has_video": { "type": "boolean", "description": "True when there is a video recording. BrokerPlus shows it; the API does not." }, "has_audio": { "type": "boolean", "description": "True when there is an audio recording." }, "summary": { "nullable": true, "description": "BrokerPlus's summary of the meeting. Null until it is written.", "type": "string" }, "created_at": { "type": "string", "description": "When the meeting was added." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "title", "provider", "status", "deal_id", "contact_id", "user_id", "started_at", "ended_at", "duration_seconds", "ended_reason", "participant_count", "has_video", "has_audio", "summary", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "sendMeetingNotetaker", "summary": "Send the notetaker into a call", "description": "Sends the BrokerPlus notetaker into a Zoom, Google Meet or Microsoft Teams call, now or at `join_at`, as the broker your key acts as. Everybody in the call sees it join. The response is `201` with the new meeting. Its transcript and summary arrive on it after the call ends: read them with `GET /v1/meetings/{id}`. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Communications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "meeting_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The Zoom, Google Meet or Microsoft Teams link of the call the notetaker joins." }, "deal_id": { "description": "The deal to file the meeting on. Leave it out to file it on none.", "type": "string" }, "bot_name": { "description": "The name everybody in the call sees. Leave it out for the brokerage's default notetaker name.", "type": "string", "minLength": 1, "maxLength": 80 }, "join_at": { "description": "When the notetaker joins, in UTC, for example `2026-10-14T15:00:00Z`. Leave it out to join now.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "meeting_url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting", "description": "The type of this record. Always `meeting`.", "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting. It is also its id in `GET /v1/communications`." }, "title": { "nullable": true, "description": "The meeting's title on the video platform. Null when the platform gave none.", "type": "string" }, "provider": { "nullable": true, "description": "What recorded it: `recall` for the BrokerPlus notetaker in a Zoom, Google Meet or Teams call, `roam` for a Roam meeting. Null before a recording arrives.", "type": "string" }, "status": { "type": "string", "description": "Where the meeting is, as the Meetings tab shows it." }, "deal_id": { "nullable": true, "description": "The deal the meeting is filed on. Null when it is on none.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the meeting is with. Null when nobody is matched.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose meeting it is. Resolve with `GET /v1/users`.", "type": "string" }, "started_at": { "nullable": true, "description": "When the recording started. Null before it starts.", "type": "string" }, "ended_at": { "nullable": true, "description": "When the recording ended. Null while it runs.", "type": "string" }, "duration_seconds": { "nullable": true, "description": "How long it was recorded, in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended_reason": { "nullable": true, "description": "Why the recording ended, as the platform said, such as `timeout_exceeded_everyone_left`.", "type": "string" }, "participant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people were in the meeting." }, "has_video": { "type": "boolean", "description": "True when there is a video recording. BrokerPlus shows it; the API does not." }, "has_audio": { "type": "boolean", "description": "True when there is an audio recording." }, "summary": { "nullable": true, "description": "BrokerPlus's summary of the meeting. Null until it is written.", "type": "string" }, "created_at": { "type": "string", "description": "When the meeting was added." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." }, "action_items": { "type": "array", "items": { "type": "string" }, "description": "The follow-ups BrokerPlus took from the meeting." }, "provider_summary": { "nullable": true, "description": "The video platform's own summary, when it writes one (Roam does). Null otherwise.", "type": "string" }, "provider_action_items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The follow-up." }, "description": { "nullable": true, "description": "More detail. Null when there is none.", "type": "string" } }, "required": [ "title", "description" ], "additionalProperties": false }, "description": "The video platform's own follow-ups, when it writes them." }, "screenshare_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long somebody shared their screen, in seconds." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the person joined with." }, "email": { "nullable": true, "description": "Their email, when the platform gave it.", "type": "string" }, "is_host": { "type": "boolean", "description": "True for the meeting's host." }, "talk_seconds": { "type": "number", "description": "How long they spoke, in seconds." }, "talk_percent": { "type": "number", "description": "Their share of all speaking time, as a percent." }, "joined_at_seconds": { "nullable": true, "description": "Seconds into the recording when they joined. Null when it is not known.", "type": "number" }, "left_at_seconds": { "nullable": true, "description": "Seconds into the recording when they left. Null when it is not known.", "type": "number" } }, "required": [ "name", "email", "is_host", "talk_seconds", "talk_percent", "joined_at_seconds", "left_at_seconds" ], "additionalProperties": false }, "description": "Who was in the meeting." }, "moments": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "join", "leave", "screenshare_on", "screenshare_off", "chat_message" ], "description": "What happened: somebody joined or left, started or stopped sharing, or wrote in the chat." }, "at_seconds": { "type": "number", "description": "Seconds into the recording when it happened." }, "name": { "type": "string", "description": "Who did it, by the name they joined with." }, "text": { "nullable": true, "description": "What they wrote, for a chat message. Null otherwise.", "type": "string" } }, "required": [ "action", "at_seconds", "name", "text" ], "additionalProperties": false }, "description": "What happened during the meeting, in order, including the chat. Empty for a Roam meeting." }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "description": "Seconds into the recording when the line starts." }, "end_seconds": { "type": "number", "description": "Seconds into the recording when it ends." }, "speaker": { "nullable": true, "description": "Who spoke, by the name they joined with.", "type": "string" }, "text": { "type": "string", "description": "What they said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript, line by line, in order." } }, "required": [ "object", "id", "title", "provider", "status", "deal_id", "contact_id", "user_id", "started_at", "ended_at", "duration_seconds", "ended_reason", "participant_count", "has_video", "has_audio", "summary", "created_at", "updated_at", "action_items", "provider_summary", "provider_action_items", "screenshare_seconds", "participants", "moments", "transcript" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not reach clients from BrokerPlus (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow this to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal is not one you can change (DEAL_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "The notetaker could not join the call (RECALL_BOT_FAILED). Check the link and try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The notetaker is not set up for BrokerPlus (RECALL_NOT_CONFIGURED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meetings/{id}": { "get": { "operationId": "getMeeting", "summary": "Retrieve a recorded meeting", "description": "One meeting with its transcript line by line, who was in it and how long each person spoke, BrokerPlus's follow-ups, and the video platform's own summary when it writes one.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting", "description": "The type of this record. Always `meeting`.", "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting. It is also its id in `GET /v1/communications`." }, "title": { "nullable": true, "description": "The meeting's title on the video platform. Null when the platform gave none.", "type": "string" }, "provider": { "nullable": true, "description": "What recorded it: `recall` for the BrokerPlus notetaker in a Zoom, Google Meet or Teams call, `roam` for a Roam meeting. Null before a recording arrives.", "type": "string" }, "status": { "type": "string", "description": "Where the meeting is, as the Meetings tab shows it." }, "deal_id": { "nullable": true, "description": "The deal the meeting is filed on. Null when it is on none.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the meeting is with. Null when nobody is matched.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose meeting it is. Resolve with `GET /v1/users`.", "type": "string" }, "started_at": { "nullable": true, "description": "When the recording started. Null before it starts.", "type": "string" }, "ended_at": { "nullable": true, "description": "When the recording ended. Null while it runs.", "type": "string" }, "duration_seconds": { "nullable": true, "description": "How long it was recorded, in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended_reason": { "nullable": true, "description": "Why the recording ended, as the platform said, such as `timeout_exceeded_everyone_left`.", "type": "string" }, "participant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people were in the meeting." }, "has_video": { "type": "boolean", "description": "True when there is a video recording. BrokerPlus shows it; the API does not." }, "has_audio": { "type": "boolean", "description": "True when there is an audio recording." }, "summary": { "nullable": true, "description": "BrokerPlus's summary of the meeting. Null until it is written.", "type": "string" }, "created_at": { "type": "string", "description": "When the meeting was added." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." }, "action_items": { "type": "array", "items": { "type": "string" }, "description": "The follow-ups BrokerPlus took from the meeting." }, "provider_summary": { "nullable": true, "description": "The video platform's own summary, when it writes one (Roam does). Null otherwise.", "type": "string" }, "provider_action_items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The follow-up." }, "description": { "nullable": true, "description": "More detail. Null when there is none.", "type": "string" } }, "required": [ "title", "description" ], "additionalProperties": false }, "description": "The video platform's own follow-ups, when it writes them." }, "screenshare_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long somebody shared their screen, in seconds." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the person joined with." }, "email": { "nullable": true, "description": "Their email, when the platform gave it.", "type": "string" }, "is_host": { "type": "boolean", "description": "True for the meeting's host." }, "talk_seconds": { "type": "number", "description": "How long they spoke, in seconds." }, "talk_percent": { "type": "number", "description": "Their share of all speaking time, as a percent." }, "joined_at_seconds": { "nullable": true, "description": "Seconds into the recording when they joined. Null when it is not known.", "type": "number" }, "left_at_seconds": { "nullable": true, "description": "Seconds into the recording when they left. Null when it is not known.", "type": "number" } }, "required": [ "name", "email", "is_host", "talk_seconds", "talk_percent", "joined_at_seconds", "left_at_seconds" ], "additionalProperties": false }, "description": "Who was in the meeting." }, "moments": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "join", "leave", "screenshare_on", "screenshare_off", "chat_message" ], "description": "What happened: somebody joined or left, started or stopped sharing, or wrote in the chat." }, "at_seconds": { "type": "number", "description": "Seconds into the recording when it happened." }, "name": { "type": "string", "description": "Who did it, by the name they joined with." }, "text": { "nullable": true, "description": "What they wrote, for a chat message. Null otherwise.", "type": "string" } }, "required": [ "action", "at_seconds", "name", "text" ], "additionalProperties": false }, "description": "What happened during the meeting, in order, including the chat. Empty for a Roam meeting." }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "description": "Seconds into the recording when the line starts." }, "end_seconds": { "type": "number", "description": "Seconds into the recording when it ends." }, "speaker": { "nullable": true, "description": "Who spoke, by the name they joined with.", "type": "string" }, "text": { "type": "string", "description": "What they said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript, line by line, in order." } }, "required": [ "object", "id", "title", "provider", "status", "deal_id", "contact_id", "user_id", "started_at", "ended_at", "duration_seconds", "ended_reason", "participant_count", "has_video", "has_audio", "summary", "created_at", "updated_at", "action_items", "provider_summary", "provider_action_items", "screenshare_seconds", "participants", "moments", "transcript" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meetings/{id}/stop": { "post": { "operationId": "stopMeetingNotetaker", "summary": "Take the notetaker out of a call", "description": "Takes the notetaker out of the call before it ends, and answers the meeting. A meeting already stopped is answered as it stands. A Roam meeting has no notetaker to take out: it is stopped from inside Roam.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting", "description": "The type of this record. Always `meeting`.", "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting. It is also its id in `GET /v1/communications`." }, "title": { "nullable": true, "description": "The meeting's title on the video platform. Null when the platform gave none.", "type": "string" }, "provider": { "nullable": true, "description": "What recorded it: `recall` for the BrokerPlus notetaker in a Zoom, Google Meet or Teams call, `roam` for a Roam meeting. Null before a recording arrives.", "type": "string" }, "status": { "type": "string", "description": "Where the meeting is, as the Meetings tab shows it." }, "deal_id": { "nullable": true, "description": "The deal the meeting is filed on. Null when it is on none.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the meeting is with. Null when nobody is matched.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose meeting it is. Resolve with `GET /v1/users`.", "type": "string" }, "started_at": { "nullable": true, "description": "When the recording started. Null before it starts.", "type": "string" }, "ended_at": { "nullable": true, "description": "When the recording ended. Null while it runs.", "type": "string" }, "duration_seconds": { "nullable": true, "description": "How long it was recorded, in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended_reason": { "nullable": true, "description": "Why the recording ended, as the platform said, such as `timeout_exceeded_everyone_left`.", "type": "string" }, "participant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people were in the meeting." }, "has_video": { "type": "boolean", "description": "True when there is a video recording. BrokerPlus shows it; the API does not." }, "has_audio": { "type": "boolean", "description": "True when there is an audio recording." }, "summary": { "nullable": true, "description": "BrokerPlus's summary of the meeting. Null until it is written.", "type": "string" }, "created_at": { "type": "string", "description": "When the meeting was added." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." }, "action_items": { "type": "array", "items": { "type": "string" }, "description": "The follow-ups BrokerPlus took from the meeting." }, "provider_summary": { "nullable": true, "description": "The video platform's own summary, when it writes one (Roam does). Null otherwise.", "type": "string" }, "provider_action_items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The follow-up." }, "description": { "nullable": true, "description": "More detail. Null when there is none.", "type": "string" } }, "required": [ "title", "description" ], "additionalProperties": false }, "description": "The video platform's own follow-ups, when it writes them." }, "screenshare_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long somebody shared their screen, in seconds." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the person joined with." }, "email": { "nullable": true, "description": "Their email, when the platform gave it.", "type": "string" }, "is_host": { "type": "boolean", "description": "True for the meeting's host." }, "talk_seconds": { "type": "number", "description": "How long they spoke, in seconds." }, "talk_percent": { "type": "number", "description": "Their share of all speaking time, as a percent." }, "joined_at_seconds": { "nullable": true, "description": "Seconds into the recording when they joined. Null when it is not known.", "type": "number" }, "left_at_seconds": { "nullable": true, "description": "Seconds into the recording when they left. Null when it is not known.", "type": "number" } }, "required": [ "name", "email", "is_host", "talk_seconds", "talk_percent", "joined_at_seconds", "left_at_seconds" ], "additionalProperties": false }, "description": "Who was in the meeting." }, "moments": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "join", "leave", "screenshare_on", "screenshare_off", "chat_message" ], "description": "What happened: somebody joined or left, started or stopped sharing, or wrote in the chat." }, "at_seconds": { "type": "number", "description": "Seconds into the recording when it happened." }, "name": { "type": "string", "description": "Who did it, by the name they joined with." }, "text": { "nullable": true, "description": "What they wrote, for a chat message. Null otherwise.", "type": "string" } }, "required": [ "action", "at_seconds", "name", "text" ], "additionalProperties": false }, "description": "What happened during the meeting, in order, including the chat. Empty for a Roam meeting." }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "description": "Seconds into the recording when the line starts." }, "end_seconds": { "type": "number", "description": "Seconds into the recording when it ends." }, "speaker": { "nullable": true, "description": "Who spoke, by the name they joined with.", "type": "string" }, "text": { "type": "string", "description": "What they said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript, line by line, in order." } }, "required": [ "object", "id", "title", "provider", "status", "deal_id", "contact_id", "user_id", "started_at", "ended_at", "duration_seconds", "ended_reason", "participant_count", "has_video", "has_audio", "summary", "created_at", "updated_at", "action_items", "provider_summary", "provider_action_items", "screenshare_seconds", "participants", "moments", "transcript" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The meeting is not one you can change, or it has no notetaker (NOT_FOUND, MEETING_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "It is a Roam meeting (NOT_SUPPORTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "The notetaker could not be reached (RECALL_BOT_FAILED). Try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "503": { "description": "The notetaker is not set up for BrokerPlus (RECALL_NOT_CONFIGURED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/meetings/{id}/sync": { "post": { "operationId": "syncMeeting", "summary": "Pull a meeting's transcript again", "description": "Asks the video platform for the meeting's recording details, transcript and summary again, as the Sync button does, for a meeting that ended without them. The work runs in the background: the response is the meeting as it stands now, and the new transcript lands on it within a few minutes.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "meeting", "description": "The type of this record. Always `meeting`.", "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "description": "Stable identifier for the meeting. It is also its id in `GET /v1/communications`." }, "title": { "nullable": true, "description": "The meeting's title on the video platform. Null when the platform gave none.", "type": "string" }, "provider": { "nullable": true, "description": "What recorded it: `recall` for the BrokerPlus notetaker in a Zoom, Google Meet or Teams call, `roam` for a Roam meeting. Null before a recording arrives.", "type": "string" }, "status": { "type": "string", "description": "Where the meeting is, as the Meetings tab shows it." }, "deal_id": { "nullable": true, "description": "The deal the meeting is filed on. Null when it is on none.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the meeting is with. Null when nobody is matched.", "type": "string" }, "user_id": { "nullable": true, "description": "The broker whose meeting it is. Resolve with `GET /v1/users`.", "type": "string" }, "started_at": { "nullable": true, "description": "When the recording started. Null before it starts.", "type": "string" }, "ended_at": { "nullable": true, "description": "When the recording ended. Null while it runs.", "type": "string" }, "duration_seconds": { "nullable": true, "description": "How long it was recorded, in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended_reason": { "nullable": true, "description": "Why the recording ended, as the platform said, such as `timeout_exceeded_everyone_left`.", "type": "string" }, "participant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people were in the meeting." }, "has_video": { "type": "boolean", "description": "True when there is a video recording. BrokerPlus shows it; the API does not." }, "has_audio": { "type": "boolean", "description": "True when there is an audio recording." }, "summary": { "nullable": true, "description": "BrokerPlus's summary of the meeting. Null until it is written.", "type": "string" }, "created_at": { "type": "string", "description": "When the meeting was added." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." }, "action_items": { "type": "array", "items": { "type": "string" }, "description": "The follow-ups BrokerPlus took from the meeting." }, "provider_summary": { "nullable": true, "description": "The video platform's own summary, when it writes one (Roam does). Null otherwise.", "type": "string" }, "provider_action_items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The follow-up." }, "description": { "nullable": true, "description": "More detail. Null when there is none.", "type": "string" } }, "required": [ "title", "description" ], "additionalProperties": false }, "description": "The video platform's own follow-ups, when it writes them." }, "screenshare_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long somebody shared their screen, in seconds." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the person joined with." }, "email": { "nullable": true, "description": "Their email, when the platform gave it.", "type": "string" }, "is_host": { "type": "boolean", "description": "True for the meeting's host." }, "talk_seconds": { "type": "number", "description": "How long they spoke, in seconds." }, "talk_percent": { "type": "number", "description": "Their share of all speaking time, as a percent." }, "joined_at_seconds": { "nullable": true, "description": "Seconds into the recording when they joined. Null when it is not known.", "type": "number" }, "left_at_seconds": { "nullable": true, "description": "Seconds into the recording when they left. Null when it is not known.", "type": "number" } }, "required": [ "name", "email", "is_host", "talk_seconds", "talk_percent", "joined_at_seconds", "left_at_seconds" ], "additionalProperties": false }, "description": "Who was in the meeting." }, "moments": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "join", "leave", "screenshare_on", "screenshare_off", "chat_message" ], "description": "What happened: somebody joined or left, started or stopped sharing, or wrote in the chat." }, "at_seconds": { "type": "number", "description": "Seconds into the recording when it happened." }, "name": { "type": "string", "description": "Who did it, by the name they joined with." }, "text": { "nullable": true, "description": "What they wrote, for a chat message. Null otherwise.", "type": "string" } }, "required": [ "action", "at_seconds", "name", "text" ], "additionalProperties": false }, "description": "What happened during the meeting, in order, including the chat. Empty for a Roam meeting." }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "start_seconds": { "type": "number", "description": "Seconds into the recording when the line starts." }, "end_seconds": { "type": "number", "description": "Seconds into the recording when it ends." }, "speaker": { "nullable": true, "description": "Who spoke, by the name they joined with.", "type": "string" }, "text": { "type": "string", "description": "What they said." } }, "required": [ "start_seconds", "end_seconds", "speaker", "text" ], "additionalProperties": false }, "description": "The transcript, line by line, in order." } }, "required": [ "object", "id", "title", "provider", "status", "deal_id", "contact_id", "user_id", "started_at", "ended_at", "duration_seconds", "ended_reason", "participant_count", "has_video", "has_audio", "summary", "created_at", "updated_at", "action_items", "provider_summary", "provider_action_items", "screenshare_seconds", "participants", "moments", "transcript" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The meeting is not one you can change, or it has no notetaker (NOT_FOUND, MEETING_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A Roam meeting with no Roam connection on file (ROAM_CONNECTION_UNKNOWN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-scripts": { "get": { "operationId": "listCallScripts", "summary": "List call scripts", "description": "The broker's own call scripts, last changed first: the questions the broker reads on a call, in sections. A script the broker retired is not listed.", "tags": [ "Call lists" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "call_script", "description": "The type of this record. Always `call_script`.", "type": "string", "enum": [ "call_script" ] }, "id": { "type": "string", "description": "Stable identifier for the call script." }, "name": { "type": "string", "description": "The name of the script." }, "description": { "nullable": true, "description": "What the script is for. Null if the broker wrote nothing.", "type": "string" }, "estimated_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About how long the call takes, in minutes. The broker's own estimate." }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the section, unique in the script." }, "label": { "type": "string", "description": "The heading of the section." }, "description": { "nullable": true, "description": "A line under the heading. Null if there is none.", "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the question, unique in the script." }, "prompt": { "type": "string", "description": "The question the broker reads out." }, "note": { "nullable": true, "description": "An instruction for whoever runs the call. Null if there is none.", "type": "string" } }, "required": [ "key", "prompt", "note" ], "additionalProperties": false }, "description": "The questions, in the order they are read." } }, "required": [ "key", "label", "description", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order." }, "created_by_user_id": { "type": "string", "description": "The broker who wrote the script. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the script was made." }, "updated_at": { "type": "string", "description": "Last change to the script. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "description", "estimated_minutes", "sections", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCallScript", "summary": "Make a call script", "description": "Makes a call script on the broker's team, the same as the Scripts pane in BrokerPlus. A question fills nothing in the application: it is a question to ask.", "tags": [ "Call lists" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The name of the script." }, "description": { "description": "What the script is for.", "type": "string", "maxLength": 300 }, "estimated_minutes": { "type": "integer", "minimum": 1, "maximum": 240, "description": "About how long the call takes, in minutes, from 1 to 240." }, "sections": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_-]+$", "description": "Your id for the section, unique in the script." }, "label": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The heading of the section." }, "description": { "description": "A line under the heading.", "type": "string", "maxLength": 300 }, "questions": { "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_-]+$", "description": "Your id for the question, unique in the script. Lowercase letters, digits, dashes, and underscores." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The question the broker reads out." }, "note": { "description": "An instruction under the question for whoever runs the call. The client never sees it.", "type": "string", "maxLength": 500 } }, "required": [ "key", "prompt" ], "additionalProperties": false }, "description": "The questions, in the order they are read. At most 40." } }, "required": [ "key", "label", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order. At most 20." } }, "required": [ "name", "estimated_minutes", "sections" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_script", "description": "The type of this record. Always `call_script`.", "type": "string", "enum": [ "call_script" ] }, "id": { "type": "string", "description": "Stable identifier for the call script." }, "name": { "type": "string", "description": "The name of the script." }, "description": { "nullable": true, "description": "What the script is for. Null if the broker wrote nothing.", "type": "string" }, "estimated_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About how long the call takes, in minutes. The broker's own estimate." }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the section, unique in the script." }, "label": { "type": "string", "description": "The heading of the section." }, "description": { "nullable": true, "description": "A line under the heading. Null if there is none.", "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the question, unique in the script." }, "prompt": { "type": "string", "description": "The question the broker reads out." }, "note": { "nullable": true, "description": "An instruction for whoever runs the call. Null if there is none.", "type": "string" } }, "required": [ "key", "prompt", "note" ], "additionalProperties": false }, "description": "The questions, in the order they are read." } }, "required": [ "key", "label", "description", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order." }, "created_by_user_id": { "type": "string", "description": "The broker who wrote the script. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the script was made." }, "updated_at": { "type": "string", "description": "Last change to the script. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "description", "estimated_minutes", "sections", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid. `details` names each field to fix (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker is on no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-scripts/{id}": { "get": { "operationId": "getCallScript", "summary": "Retrieve a call script", "description": "One call script, with every section and question.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_script", "description": "The type of this record. Always `call_script`.", "type": "string", "enum": [ "call_script" ] }, "id": { "type": "string", "description": "Stable identifier for the call script." }, "name": { "type": "string", "description": "The name of the script." }, "description": { "nullable": true, "description": "What the script is for. Null if the broker wrote nothing.", "type": "string" }, "estimated_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About how long the call takes, in minutes. The broker's own estimate." }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the section, unique in the script." }, "label": { "type": "string", "description": "The heading of the section." }, "description": { "nullable": true, "description": "A line under the heading. Null if there is none.", "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the question, unique in the script." }, "prompt": { "type": "string", "description": "The question the broker reads out." }, "note": { "nullable": true, "description": "An instruction for whoever runs the call. Null if there is none.", "type": "string" } }, "required": [ "key", "prompt", "note" ], "additionalProperties": false }, "description": "The questions, in the order they are read." } }, "required": [ "key", "label", "description", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order." }, "created_by_user_id": { "type": "string", "description": "The broker who wrote the script. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the script was made." }, "updated_at": { "type": "string", "description": "Last change to the script. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "description", "estimated_minutes", "sections", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCallScript", "summary": "Update a call script", "description": "Changes the fields you send. `sections` replaces every section of the script.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The name of the script." }, "description": { "description": "What the script is for.", "type": "string", "maxLength": 300 }, "estimated_minutes": { "type": "integer", "minimum": 1, "maximum": 240, "description": "About how long the call takes, in minutes, from 1 to 240." }, "sections": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_-]+$", "description": "Your id for the section, unique in the script." }, "label": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The heading of the section." }, "description": { "description": "A line under the heading.", "type": "string", "maxLength": 300 }, "questions": { "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_-]+$", "description": "Your id for the question, unique in the script. Lowercase letters, digits, dashes, and underscores." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The question the broker reads out." }, "note": { "description": "An instruction under the question for whoever runs the call. The client never sees it.", "type": "string", "maxLength": 500 } }, "required": [ "key", "prompt" ], "additionalProperties": false }, "description": "The questions, in the order they are read. At most 40." } }, "required": [ "key", "label", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order. At most 20." } }, "additionalProperties": false, "description": "Send only the fields to change. `sections` replaces every section." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_script", "description": "The type of this record. Always `call_script`.", "type": "string", "enum": [ "call_script" ] }, "id": { "type": "string", "description": "Stable identifier for the call script." }, "name": { "type": "string", "description": "The name of the script." }, "description": { "nullable": true, "description": "What the script is for. Null if the broker wrote nothing.", "type": "string" }, "estimated_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About how long the call takes, in minutes. The broker's own estimate." }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the section, unique in the script." }, "label": { "type": "string", "description": "The heading of the section." }, "description": { "nullable": true, "description": "A line under the heading. Null if there is none.", "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The id of the question, unique in the script." }, "prompt": { "type": "string", "description": "The question the broker reads out." }, "note": { "nullable": true, "description": "An instruction for whoever runs the call. Null if there is none.", "type": "string" } }, "required": [ "key", "prompt", "note" ], "additionalProperties": false }, "description": "The questions, in the order they are read." } }, "required": [ "key", "label", "description", "questions" ], "additionalProperties": false }, "description": "The sections of the script, in order." }, "created_by_user_id": { "type": "string", "description": "The broker who wrote the script. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the script was made." }, "updated_at": { "type": "string", "description": "Last change to the script. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "description", "estimated_minutes", "sections", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The script does not exist, was retired, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCallScript", "summary": "Retire a call script", "description": "Retires the script. It is no longer listed, but a call that already used it still names it. A retired script cannot be changed or brought back.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The script does not exist, was retired, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-introductions": { "get": { "operationId": "listPartnerIntroductions", "summary": "List introductions to partners", "description": "The clients and leads the broker introduced to referral partners, newest first: the `sent` side of the Partners page. Only introductions where the broker can read both people are listed.", "tags": [ "Referral partners" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "partner_contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only introductions to this partner." }, { "name": "introduced_contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only introductions of this client or lead." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only introductions for this deal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_introduction", "description": "The type of this record. Always `partner_introduction`.", "type": "string", "enum": [ "partner_introduction" ] }, "id": { "type": "string", "description": "Stable identifier for the introduction." }, "partner_contact_id": { "type": "string", "description": "The referral partner the broker introduced someone to." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "introduced_contact_id": { "type": "string", "description": "The client or lead the broker introduced." }, "introduced_name": { "type": "string", "description": "The introduced person's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the introduction was for. Null when it was for none.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on the introduction. Null when there is none.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the broker made the introduction." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the introduction was recorded." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "partner_contact_id", "partner_name", "introduced_contact_id", "introduced_name", "deal_id", "note", "occurred_at", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createPartnerIntroduction", "summary": "Record an introduction", "description": "Records that the broker introduced a client or lead to a partner, as the Partners page does. A person is introduced to a partner once: recording the same pair again changes the note, deal, and date of the one introduction. BrokerPlus sends nothing to either of them.", "tags": [ "Referral partners" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partner_contact_id": { "type": "string", "minLength": 1, "description": "The partner's contact. Find it from `contact_id` in `GET /v1/referral-partners`." }, "introduced_contact_id": { "type": "string", "minLength": 1, "description": "The contact of the client or lead the broker introduced." }, "deal_id": { "description": "The deal the introduction was for.", "nullable": true, "type": "string", "minLength": 1 }, "note": { "description": "A note on the introduction.", "nullable": true, "type": "string", "maxLength": 20000 }, "occurred_at": { "description": "When the broker made the introduction, as ISO 8601. Defaults to now on a new introduction.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "partner_contact_id", "introduced_contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_introduction", "description": "The type of this record. Always `partner_introduction`.", "type": "string", "enum": [ "partner_introduction" ] }, "id": { "type": "string", "description": "Stable identifier for the introduction." }, "partner_contact_id": { "type": "string", "description": "The referral partner the broker introduced someone to." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "introduced_contact_id": { "type": "string", "description": "The client or lead the broker introduced." }, "introduced_name": { "type": "string", "description": "The introduced person's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the introduction was for. Null when it was for none.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on the introduction. Null when there is none.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the broker made the introduction." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the introduction was recorded." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "partner_contact_id", "partner_name", "introduced_contact_id", "introduced_name", "deal_id", "note", "occurred_at", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid, or both ids are the same person (INVALID_INTRODUCTION).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "A contact or the deal does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-introductions/{id}": { "get": { "operationId": "getPartnerIntroduction", "summary": "Retrieve an introduction", "description": "One introduction of a client or lead to a partner.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_introduction", "description": "The type of this record. Always `partner_introduction`.", "type": "string", "enum": [ "partner_introduction" ] }, "id": { "type": "string", "description": "Stable identifier for the introduction." }, "partner_contact_id": { "type": "string", "description": "The referral partner the broker introduced someone to." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "introduced_contact_id": { "type": "string", "description": "The client or lead the broker introduced." }, "introduced_name": { "type": "string", "description": "The introduced person's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the introduction was for. Null when it was for none.", "type": "string" }, "note": { "nullable": true, "description": "The broker's note on the introduction. Null when there is none.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the broker made the introduction." }, "created_by_user_id": { "nullable": true, "description": "The broker who recorded it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the introduction was recorded." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "partner_contact_id", "partner_name", "introduced_contact_id", "introduced_name", "deal_id", "note", "occurred_at", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deletePartnerIntroduction", "summary": "Delete an introduction", "description": "Deletes the record of the introduction. Both contacts stay.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The introduction does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-company-notes": { "get": { "operationId": "listPartnerCompanyNotes", "summary": "List partner firm notes", "description": "The brokerage's notes on its partners' firms, by firm name. A note usually says which office the firm's partners work from. Every broker in the brokerage reads and writes the same notes, as on the Partners page.", "tags": [ "Referral partners" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "company", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the note on this firm. Case is ignored." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_company_note", "description": "The type of this record. Always `partner_company_note`.", "type": "string", "enum": [ "partner_company_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "company": { "type": "string", "description": "The partner firm, as the brokerage's partners spell it. This is the `company` on a partner in `GET /v1/referral-partners`." }, "note": { "type": "string", "description": "The brokerage's note on the firm, such as which office its partners work from." }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "company", "note", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "savePartnerCompanyNote", "summary": "Write a partner firm note", "description": "Writes the note on a firm. A firm has one note: if it already has one, this replaces its text and returns the same note.", "tags": [ "Referral partners" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The partner firm. Case is ignored: the note is saved under the spelling the brokerage's partners already use." }, "note": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The note, at most 2000 characters. To remove a note, delete it." } }, "required": [ "company", "note" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_company_note", "description": "The type of this record. Always `partner_company_note`.", "type": "string", "enum": [ "partner_company_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "company": { "type": "string", "description": "The partner firm, as the brokerage's partners spell it. This is the `company` on a partner in `GET /v1/referral-partners`." }, "note": { "type": "string", "description": "The brokerage's note on the firm, such as which office its partners work from." }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "company", "note", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-company-notes/{id}": { "get": { "operationId": "getPartnerCompanyNote", "summary": "Retrieve a partner firm note", "description": "One note on a partner firm.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_company_note", "description": "The type of this record. Always `partner_company_note`.", "type": "string", "enum": [ "partner_company_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "company": { "type": "string", "description": "The partner firm, as the brokerage's partners spell it. This is the `company` on a partner in `GET /v1/referral-partners`." }, "note": { "type": "string", "description": "The brokerage's note on the firm, such as which office its partners work from." }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "company", "note", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updatePartnerCompanyNote", "summary": "Update a partner firm note", "description": "Replaces the text of the note.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The note, at most 2000 characters. To remove a note, delete it." } }, "required": [ "note" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_company_note", "description": "The type of this record. Always `partner_company_note`.", "type": "string", "enum": [ "partner_company_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "company": { "type": "string", "description": "The partner firm, as the brokerage's partners spell it. This is the `company` on a partner in `GET /v1/referral-partners`." }, "note": { "type": "string", "description": "The brokerage's note on the firm, such as which office its partners work from." }, "created_at": { "type": "string", "description": "When the note was first written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "company", "note", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The note does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deletePartnerCompanyNote", "summary": "Delete a partner firm note", "description": "Deletes the note. The firm and its partners stay.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The note does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/agent-instructions": { "get": { "operationId": "listAgentInstructions", "summary": "List the assistant's instructions", "description": "The standing instructions the broker gave their assistant, the same list as Assistant settings in BrokerPlus: the brokerage's instructions and the broker's team's, by topic and then oldest first.", "tags": [ "Assistant" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ] }, "description": "Only the instructions under this topic." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "agent_instruction", "description": "The type of this record. Always `agent_instruction`.", "type": "string", "enum": [ "agent_instruction" ] }, "id": { "type": "string", "description": "Stable identifier for the instruction." }, "scope": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` applies to one team's work. `brokerage` applies to every team, and only an admin writes one." }, "team_id": { "nullable": true, "description": "The team the instruction applies to. Null for a brokerage instruction.", "type": "string" }, "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "title": { "nullable": true, "description": "A short name for a long instruction. Null when it has none.", "type": "string" }, "body": { "type": "string", "description": "The instruction, in the broker's words." }, "enabled": { "type": "boolean", "description": "False while the broker has it switched off. The assistant then ignores it." }, "editable": { "type": "boolean", "description": "True when the key's broker can change or delete it. Only an admin can change a brokerage instruction." }, "created_by_user_id": { "nullable": true, "description": "The broker who wrote it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the instruction was written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "scope", "team_id", "topic", "title", "body", "enabled", "editable", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAgentInstruction", "summary": "Give the assistant an instruction", "description": "Adds a standing instruction that the assistant follows from its next run. A topic holds at most 8 instructions for a team, and 8 for the brokerage.", "tags": [ "Assistant" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The instruction, at most 2000 characters." }, "title": { "description": "A short name, at most 80 characters.", "nullable": true, "type": "string", "maxLength": 80 }, "scope": { "default": "team", "description": "`team` (the default) for the broker's own team. `brokerage` for every team: only an admin can.", "type": "string", "enum": [ "team", "brokerage" ] } }, "required": [ "topic", "body", "scope" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "agent_instruction", "description": "The type of this record. Always `agent_instruction`.", "type": "string", "enum": [ "agent_instruction" ] }, "id": { "type": "string", "description": "Stable identifier for the instruction." }, "scope": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` applies to one team's work. `brokerage` applies to every team, and only an admin writes one." }, "team_id": { "nullable": true, "description": "The team the instruction applies to. Null for a brokerage instruction.", "type": "string" }, "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "title": { "nullable": true, "description": "A short name for a long instruction. Null when it has none.", "type": "string" }, "body": { "type": "string", "description": "The instruction, in the broker's words." }, "enabled": { "type": "boolean", "description": "False while the broker has it switched off. The assistant then ignores it." }, "editable": { "type": "boolean", "description": "True when the key's broker can change or delete it. Only an admin can change a brokerage instruction." }, "created_by_user_id": { "nullable": true, "description": "The broker who wrote it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the instruction was written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "scope", "team_id", "topic", "title", "body", "enabled", "editable", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid (VALIDATION_ERROR), or the broker is on no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only an admin can add a `brokerage` instruction (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The topic already holds 8 instructions. Change or delete one first (LIMIT_REACHED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/agent-instructions/{id}": { "get": { "operationId": "getAgentInstruction", "summary": "Retrieve an instruction", "description": "One standing instruction to the assistant.", "tags": [ "Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "agent_instruction", "description": "The type of this record. Always `agent_instruction`.", "type": "string", "enum": [ "agent_instruction" ] }, "id": { "type": "string", "description": "Stable identifier for the instruction." }, "scope": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` applies to one team's work. `brokerage` applies to every team, and only an admin writes one." }, "team_id": { "nullable": true, "description": "The team the instruction applies to. Null for a brokerage instruction.", "type": "string" }, "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "title": { "nullable": true, "description": "A short name for a long instruction. Null when it has none.", "type": "string" }, "body": { "type": "string", "description": "The instruction, in the broker's words." }, "enabled": { "type": "boolean", "description": "False while the broker has it switched off. The assistant then ignores it." }, "editable": { "type": "boolean", "description": "True when the key's broker can change or delete it. Only an admin can change a brokerage instruction." }, "created_by_user_id": { "nullable": true, "description": "The broker who wrote it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the instruction was written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "scope", "team_id", "topic", "title", "body", "enabled", "editable", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateAgentInstruction", "summary": "Update an instruction", "description": "Changes the fields you send. Send `enabled: false` to switch an instruction off and keep it.", "tags": [ "Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The instruction, at most 2000 characters." }, "title": { "description": "A short name, at most 80 characters.", "nullable": true, "type": "string", "maxLength": 80 }, "enabled": { "description": "False switches the instruction off without deleting it.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "agent_instruction", "description": "The type of this record. Always `agent_instruction`.", "type": "string", "enum": [ "agent_instruction" ] }, "id": { "type": "string", "description": "Stable identifier for the instruction." }, "scope": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` applies to one team's work. `brokerage` applies to every team, and only an admin writes one." }, "team_id": { "nullable": true, "description": "The team the instruction applies to. Null for a brokerage instruction.", "type": "string" }, "topic": { "type": "string", "enum": [ "always", "client_writing", "tasks", "stage_moves", "documents", "lenders" ], "description": "When the assistant applies the instruction: `always` (always), `client_writing` (writing to clients), `tasks` (assigning tasks), `stage_moves` (moving deals forward), `documents` (chasing documents), `lenders` (dealing with lenders)." }, "title": { "nullable": true, "description": "A short name for a long instruction. Null when it has none.", "type": "string" }, "body": { "type": "string", "description": "The instruction, in the broker's words." }, "enabled": { "type": "boolean", "description": "False while the broker has it switched off. The assistant then ignores it." }, "editable": { "type": "boolean", "description": "True when the key's broker can change or delete it. Only an admin can change a brokerage instruction." }, "created_by_user_id": { "nullable": true, "description": "The broker who wrote it. Resolve with `GET /v1/users`. Null once that broker is removed.", "type": "string" }, "created_at": { "type": "string", "description": "When the instruction was written." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "scope", "team_id", "topic", "title", "body", "enabled", "editable", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only an admin can change a brokerage instruction (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The instruction does not exist, or the broker cannot see it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteAgentInstruction", "summary": "Delete an instruction", "description": "Deletes the instruction. The assistant stops following it from its next run.", "tags": [ "Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only an admin can delete a brokerage instruction (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The instruction does not exist, or the broker cannot see it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-lists": { "get": { "operationId": "listCallLists", "summary": "List call lists", "description": "The broker's call lists, last changed first, with how many people are on each and how many are still to call. Read the people with `GET /call-lists/{id}/entries`.", "tags": [ "Call lists" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCallList", "summary": "Make a call list", "description": "Makes a call list on the broker's team, with the contacts or deals you name. Add more people later with `POST /call-lists/{id}/entries`. Nobody is called or sent anything.", "tags": [ "Call lists" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The name of the list." }, "entries": { "description": "The people to put on the list, at most 500. A contact or deal the broker cannot reach is left out, and a person named two times is put on once.", "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "contact_id": { "description": "A contact to call.", "type": "string", "minLength": 1 }, "deal_id": { "description": "A deal. With no `contact_id`, BrokerPlus puts the deal's primary applicant on the list. The row shows the deal.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid. `details` names each field to fix (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker is on no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-lists/{id}": { "get": { "operationId": "getCallList", "summary": "Retrieve a call list", "description": "One call list, with its counts.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCallList", "summary": "Rename a call list", "description": "Changes the name of the list.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The new name of the list." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The list does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCallList", "summary": "Delete a call list", "description": "Deletes the list and every row on it, with their outcomes and notes. The contacts and their calls stay.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The list does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-lists/import": { "post": { "operationId": "importCallList", "summary": "Make a call list from rows", "description": "Makes a call list from rows of names, numbers, and emails, for example the rows of a spreadsheet. Each row is matched to a contact by email, then by number. A row that matches nobody stays on the list only, unless you send `add_to_contacts`. Read the file yourself and send its rows: this call does not take a file.", "tags": [ "Call lists" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The name of the new list." }, "rows": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The person's full name." }, "phone": { "description": "The number to call. Any format.", "type": "string", "maxLength": 50 }, "email": { "description": "The person's email.", "type": "string", "maxLength": 320 } }, "required": [ "name" ], "additionalProperties": false }, "description": "The people on the list, at most 5000, in order. BrokerPlus matches each one to a contact by email, then by number. A row named two times is put on once." }, "add_to_contacts": { "description": "Defaults to `false`: a row that matches no contact stays on the list only. With `true`, BrokerPlus adds each of those rows to the contacts.", "type": "boolean" } }, "required": [ "name", "rows" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." }, "contacts_created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many contacts the import added. Zero unless `add_to_contacts`." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at", "contacts_created" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid. `details` names each field to fix (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker is on no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-lists/{id}/entries": { "get": { "operationId": "listCallListEntries", "summary": "List the people on a call list", "description": "The rows of a call list, in the order the broker works them, each with its outcome and note.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "called", "no_answer", "follow_up", "done" ] }, "description": "Only rows with this outcome." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "call_list_entry", "description": "The type of this record. Always `call_list_entry`.", "type": "string", "enum": [ "call_list_entry" ] }, "id": { "type": "string", "description": "Stable identifier for the row." }, "call_list_id": { "type": "string", "description": "The list the row is on." }, "contact_id": { "nullable": true, "description": "The contact to call. Null for a person who came in on an import and was not added to the contacts.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal that put this person on the list, if any.", "type": "string" }, "name": { "type": "string", "description": "The person's name, from the contact or, with no contact, from the import." }, "email": { "nullable": true, "description": "The person's email, read the same way as `name`.", "type": "string" }, "phone": { "nullable": true, "description": "The number to call, read the same way as `name`.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "called", "no_answer", "follow_up", "done" ], "description": "The outcome of the call: `pending` (not called yet), `called`, `no_answer`, `follow_up`, or `done`. The broker can set any outcome at any time." }, "note": { "nullable": true, "description": "The broker's note on the row.", "type": "string" }, "called_at": { "nullable": true, "description": "When the row first left `pending`. It stays when the outcome changes again, and clears when the row goes back to `pending`.", "type": "string" }, "called_by_user_id": { "nullable": true, "description": "The broker who first worked the row. Null while it is `pending`.", "type": "string" }, "called_by_name": { "nullable": true, "description": "The name of `called_by_user_id`.", "type": "string" }, "created_at": { "type": "string", "description": "When the person was put on the list." }, "updated_at": { "type": "string", "description": "Last change to the row. Use it with `updated_since`." } }, "required": [ "object", "id", "call_list_id", "contact_id", "deal_id", "name", "email", "phone", "status", "note", "called_at", "called_by_user_id", "called_by_name", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "addCallListEntries", "summary": "Add people to a call list", "description": "Puts contacts, deals, or people typed in by name on the list. A person already on the list is not added again, and their outcome and note stay as they are. A contact or deal the broker cannot reach is left out.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "description": "Contacts or deals to put on the list, at most 500.", "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "contact_id": { "description": "A contact to call.", "type": "string", "minLength": 1 }, "deal_id": { "description": "A deal. With no `contact_id`, BrokerPlus puts the deal's primary applicant on the list. The row shows the deal.", "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "people": { "description": "People typed in by name, at most 50. BrokerPlus matches each one to a contact by email, then by number. A person who matches nobody is added to the contacts, unless `add_to_contacts` is `false`.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The person's full name." }, "phone": { "description": "The number to call. Any format.", "type": "string", "maxLength": 50 }, "email": { "description": "The person's email.", "type": "string", "maxLength": 320 }, "add_to_contacts": { "description": "Defaults to `true`. With `false`, a person who is not a contact yet stays on the list only and is not added to the contacts.", "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list", "description": "The type of this record. Always `call_list`.", "type": "string", "enum": [ "call_list" ] }, "id": { "type": "string", "description": "Stable identifier for the call list." }, "name": { "type": "string", "description": "The name of the list." }, "entry_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people are on the list." }, "pending_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them nobody has called yet (`status` of `pending`)." }, "created_by_user_id": { "type": "string", "description": "The broker who made the list. Resolve with `GET /v1/users`." }, "created_at": { "type": "string", "description": "When the list was made." }, "updated_at": { "type": "string", "description": "Last change to the list itself. Use it with `updated_since`." }, "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people this call put on the list. A person already on it is not added again." } }, "required": [ "object", "id", "name", "entry_count", "pending_count", "created_by_user_id", "created_at", "updated_at", "added" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid. `details` names each field to fix (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The list does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/call-lists/{id}/entries/{entry_id}": { "patch": { "operationId": "updateCallListEntry", "summary": "Record a call outcome", "description": "Sets the outcome of a row, its note, or both. The outcome is a field, not a step: any outcome can follow any other, as in BrokerPlus.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "The outcome of the call. Any outcome can follow any other, as in BrokerPlus. Leaving `pending` records who worked the row and when; going back to `pending` clears both.", "type": "string", "enum": [ "pending", "called", "no_answer", "follow_up", "done" ] }, "note": { "description": "The broker's note on the row. Null clears it.", "nullable": true, "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "call_list_entry", "description": "The type of this record. Always `call_list_entry`.", "type": "string", "enum": [ "call_list_entry" ] }, "id": { "type": "string", "description": "Stable identifier for the row." }, "call_list_id": { "type": "string", "description": "The list the row is on." }, "contact_id": { "nullable": true, "description": "The contact to call. Null for a person who came in on an import and was not added to the contacts.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal that put this person on the list, if any.", "type": "string" }, "name": { "type": "string", "description": "The person's name, from the contact or, with no contact, from the import." }, "email": { "nullable": true, "description": "The person's email, read the same way as `name`.", "type": "string" }, "phone": { "nullable": true, "description": "The number to call, read the same way as `name`.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "called", "no_answer", "follow_up", "done" ], "description": "The outcome of the call: `pending` (not called yet), `called`, `no_answer`, `follow_up`, or `done`. The broker can set any outcome at any time." }, "note": { "nullable": true, "description": "The broker's note on the row.", "type": "string" }, "called_at": { "nullable": true, "description": "When the row first left `pending`. It stays when the outcome changes again, and clears when the row goes back to `pending`.", "type": "string" }, "called_by_user_id": { "nullable": true, "description": "The broker who first worked the row. Null while it is `pending`.", "type": "string" }, "called_by_name": { "nullable": true, "description": "The name of `called_by_user_id`.", "type": "string" }, "created_at": { "type": "string", "description": "When the person was put on the list." }, "updated_at": { "type": "string", "description": "Last change to the row. Use it with `updated_since`." } }, "required": [ "object", "id", "call_list_id", "contact_id", "deal_id", "name", "email", "phone", "status", "note", "called_at", "called_by_user_id", "called_by_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The row does not exist, or the broker cannot change its list (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCallListEntry", "summary": "Take a person off a call list", "description": "Deletes the row. The contact stays.", "tags": [ "Call lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The row does not exist, or the broker cannot change its list (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates": { "get": { "operationId": "listRequestTemplates", "summary": "List request templates", "description": "The templates in the broker's request library, as BrokerPlus shows them when the broker asks a client for something. A team shares its broker's library. The templates that BrokerPlus supplies come first, then the most recently changed. `updated_since` pages on when each template last changed.", "tags": [ "Request templates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createRequestTemplate", "summary": "Create a request template", "description": "Adds an empty template to the broker's request library. Add its items with `POST /request-templates/{id}/items`. To start from a template that is already there, use `POST /request-templates/{id}/duplicate`. Supports `Idempotency-Key`.", "tags": [ "Request templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The template's name." }, "description": { "description": "What the template is for.", "nullable": true, "type": "string", "maxLength": 2000 }, "category": { "description": "The shelf of the request library to put it on.", "nullable": true, "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}": { "get": { "operationId": "getRequestTemplate", "summary": "Retrieve a request template", "description": "One request template, with every item on it in order.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateRequestTemplate", "summary": "Update a request template", "description": "Changes the name, the description or the shelf of a template, or turns its public link on or off. Only the fields you send change. Requests that were sent before do not change.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The template's name.", "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "What the template is for. Send null to remove it.", "nullable": true, "type": "string", "maxLength": 2000 }, "category": { "description": "The shelf of the request library. Send null to put it under Other.", "nullable": true, "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "public_link_enabled": { "description": "`true` turns on the public link that anybody can start a request from. The first time, this makes `public_url`. BrokerPlus sends the link to nobody.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteRequestTemplate", "summary": "Delete a request template", "description": "Removes the template from the broker's request library. Requests that were sent from it do not change.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/duplicate": { "post": { "operationId": "duplicateRequestTemplate", "summary": "Copy a request template", "description": "Makes a copy of the template, with all its items, in the same library. The copy is the broker's own: it is not a template that BrokerPlus supplies, so it cannot be reset. Supports `Idempotency-Key`.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the copy. The default is the template's name followed by `(copy)`.", "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/favourite": { "post": { "operationId": "favouriteRequestTemplate", "summary": "Star a request template", "description": "Stars the template for the broker your key acts as, as the star in the request library does. A star is one person's shortcut: the rest of the team does not see it. Starring a starred template changes nothing.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/unfavourite": { "post": { "operationId": "unfavouriteRequestTemplate", "summary": "Remove the star from a request template", "description": "Removes the star of the broker your key acts as. A template with no star changes nothing.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/reset": { "post": { "operationId": "resetRequestTemplate", "summary": "Reset a request template", "description": "Puts every item that came with a template that BrokerPlus supplies back the way BrokerPlus wrote it. Items the broker added stay as they are.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "BrokerPlus did not supply this template, so it has no original (NO_DEFAULT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/items": { "post": { "operationId": "createRequestTemplateItem", "summary": "Add an item to a request template", "description": "Adds a question, a document to ask for, or another item to the template. A `doc_request` needs `document_type`. To add a form to sign, use BrokerPlus: the form needs its PDF. Supports `Idempotency-Key`.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_]+$", "description": "The item's name inside the template: lowercase letters, digits and `_`. It must be unique on the template." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do. To add a form to sign, use BrokerPlus: the form needs its PDF." }, "position": { "description": "Where to put the item. The default is after the last item.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The name of the item that the client reads." }, "description": { "description": "The text under the name.", "nullable": true, "type": "string", "maxLength": 2000 }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "If the client must do it. The default is `required`." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked. The default is `either`." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item. The default is `both`." }, "document_type": { "description": "For a `doc_request`, the document to ask for: a `code` from `GET /v1/document-types`, or one of the team's own document types. Required for a `doc_request`.", "type": "string", "minLength": 1 }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind. Copy the shape from an item of the same kind." }, "visibility": { "maxItems": 50, "type": "array", "items": {}, "description": "The conditions that show the item only for some answers." }, "broker_note": { "description": "A note that the client sees on the item.", "nullable": true, "type": "string", "maxLength": 2000 }, "help_title": { "description": "The title of the item's help text.", "nullable": true, "type": "string", "maxLength": 200 }, "help_body_html": { "description": "The item's help text, as HTML. Unsafe HTML is removed.", "nullable": true, "type": "string", "maxLength": 20000 } }, "required": [ "key", "kind", "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "An item with this `key` is already on the template (DUPLICATE_KEY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The document type is not one the client can be asked for (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/items/{itemId}": { "patch": { "operationId": "updateRequestTemplateItem", "summary": "Update an item on a request template", "description": "Changes an item on the template. Only the fields you send change. A form to sign is checked as BrokerPlus checks it: every signer must have a place to sign. To change the order of the items, use `POST /request-templates/{id}/items/reorder`.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The name of the item that the client reads." }, "description": { "description": "The text under the name.", "nullable": true, "type": "string", "maxLength": 2000 }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "If the client must do it. The default is `required`." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked. The default is `either`." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item. The default is `both`." }, "document_type": { "description": "For a `doc_request`, the document to ask for instead. Not accepted for other kinds.", "type": "string", "minLength": 1 }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind. Copy the shape from an item of the same kind." }, "visibility": { "maxItems": 50, "type": "array", "items": {}, "description": "The conditions that show the item only for some answers." }, "broker_note": { "description": "A note that the client sees on the item.", "nullable": true, "type": "string", "maxLength": 2000 }, "help_title": { "description": "The title of the item's help text.", "nullable": true, "type": "string", "maxLength": 200 }, "help_body_html": { "description": "The item's help text, as HTML. Unsafe HTML is removed.", "nullable": true, "type": "string", "maxLength": 20000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template or the item is not there (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The document type is not one the client can be asked for (VALIDATION_ERROR), or the form to sign is not complete (INVALID_SIGNING_CONFIG, MISSING_SIGNATURE_FIELD).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteRequestTemplateItem", "summary": "Remove an item from a request template", "description": "Removes the item from the template. Requests that were sent before do not change. Removing an item that is not there returns 200.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/items/reorder": { "post": { "operationId": "reorderRequestTemplateItems", "summary": "Put the items of a request template in order", "description": "Sets the order of every item on the template. Send each item once, in the new order.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Every item on the template, by `id`, in the new order. The first one goes first." } }, "required": [ "item_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template", "description": "The type of this record. Always `request_template`.", "type": "string", "enum": [ "request_template" ] }, "id": { "type": "string", "description": "Stable identifier for the request template. Send it as `template_id` to ask a client for its documents." }, "name": { "type": "string", "description": "The template's name, as the broker's request library shows it." }, "description": { "nullable": true, "description": "What the template is for. Null when there is none.", "type": "string" }, "category": { "nullable": true, "description": "The shelf of the request library the template is on. Null shows it under Other.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance" ] }, "is_default": { "type": "boolean", "description": "`true` for a template that BrokerPlus supplies. You can change it, and reset it to the original later." }, "broker_user_id": { "type": "string", "description": "The broker whose request library holds the template. A team shares its broker's library." }, "team_id": { "nullable": true, "description": "The team whose brand the client sees on the template's public link.", "type": "string" }, "public_link_enabled": { "type": "boolean", "description": "`true` when anybody who has the template's public link can start a request from it." }, "public_url": { "nullable": true, "description": "The template's public link. Null until the link is turned on once. The link stays the same when you turn it off and on again.", "type": "string" }, "favourite": { "type": "boolean", "description": "`true` when the broker your key acts as starred the template." }, "item_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items the template has." }, "edited_at": { "nullable": true, "description": "When a broker last changed the template. Null when nobody has changed it.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template record last changed, for a sync." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every item on the template, in order." } }, "required": [ "object", "id", "name", "description", "category", "is_default", "broker_user_id", "team_id", "public_link_enabled", "public_url", "favourite", "item_count", "edited_at", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template is not in the broker's request library (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The list does not hold every item on the template exactly once (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/request-templates/{id}/items/{itemId}/reset": { "post": { "operationId": "resetRequestTemplateItem", "summary": "Reset an item on a request template", "description": "Puts one item back the way BrokerPlus wrote it, on a template that BrokerPlus supplies.", "tags": [ "Request templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "request_template_item", "description": "The type of this record. Always `request_template_item`.", "type": "string", "enum": [ "request_template_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "template_id": { "type": "string", "description": "The request template the item is on." }, "key": { "type": "string", "description": "The item's name inside its template. It is unique on the template and does not change when it is sent." }, "kind": { "type": "string", "enum": [ "intake_field", "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `intake_field` answer a question, `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` agree to a statement, `identity_verification` prove who they are." }, "label": { "type": "string", "description": "The name of the item that the client reads." }, "description": { "nullable": true, "description": "The text under the name. Null when there is none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` when the client must do it, `optional` when they can skip it, `required_with_dismissible_reason` when they must do it or tell the broker why they cannot." }, "role": { "type": "string", "enum": [ "primary", "co_applicant", "either" ], "description": "Who is asked: `primary` the main applicant, `co_applicant` each co-applicant, `either` every applicant." }, "show_on": { "type": "string", "enum": [ "both", "single", "joint" ], "description": "Which applications show the item: `both`, `single` only an application with one applicant, `joint` only an application with more than one." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type it asks for, from `GET /v1/document-types`. Null for other kinds.", "type": "string" }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings for the item's kind, as BrokerPlus stores them. For example, the type and the choices of a question. A `doc_request` keeps its document type here as `docType`." }, "visibility": { "type": "array", "items": {}, "description": "The conditions that show the item only for some answers. Each one names an answer, a comparison and a value. An empty list shows the item always." }, "broker_note": { "nullable": true, "description": "A note from the broker that the client sees on the item. Null when there is none.", "type": "string" }, "help_title": { "nullable": true, "description": "The title of the item's help text. Null uses the standard title.", "type": "string" }, "help_body_html": { "nullable": true, "description": "The item's help text, as HTML. Null uses the standard help text.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The place of the item on the template. The lowest number is first." }, "created_at": { "type": "string", "description": "When the item was added." }, "updated_at": { "type": "string", "description": "When the item last changed." } }, "required": [ "object", "id", "template_id", "key", "kind", "label", "description", "required_mode", "role", "show_on", "document_type", "config", "visibility", "broker_note", "help_title", "help_body_html", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template or the item is not there (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "BrokerPlus did not supply this item, so it has no original (NO_DEFAULT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intake-link": { "get": { "operationId": "getIntakeLink", "summary": "Retrieve the standing intake link", "description": "The one link a broker shares with anybody who wants to start an application. It is not tied to a client and it does not expire. The url is null until the link has been enabled once.", "tags": [ "Intakes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the link accepts new intakes right now." }, "url": { "nullable": true, "description": "The link to share. Null until it has been enabled once. It does not change when you disable it.", "type": "string" } }, "required": [ "enabled", "url" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateIntakeLink", "summary": "Turn the standing intake link on or off", "description": "Enabling the link for the first time creates its url. Disabling it stops new intakes but keeps the url, so a link already printed somewhere works again when you enable it.", "tags": [ "Intakes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "`true` to accept new intakes on the link, `false` to stop." } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the link accepts new intakes right now." }, "url": { "nullable": true, "description": "The link to share. Null until it has been enabled once. It does not change when you disable it.", "type": "string" } }, "required": [ "enabled", "url" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/captured-answers": { "get": { "operationId": "listCapturedAnswers", "summary": "List what a client said on a call", "description": "The answers BrokerPlus heard from this person on a call or in an email, ready to fill in the next intake they are sent. This is the preview the broker sees before sending an intake. Each answer keeps what the person said, word for word, in `heard_as`. An answer that already filled in an intake has `applied_at`. These are read-only: BrokerPlus writes them from the call, and the intake uses them up.", "tags": [ "Intake" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "pending", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` for only the answers still waiting to fill in an intake, `false` for only the ones already used." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "captured_answer", "description": "The type of this record. Always `captured_answer`.", "type": "string", "enum": [ "captured_answer" ] }, "id": { "type": "string", "description": "Stable identifier for the answer." }, "contact_id": { "type": "string", "description": "The person who gave the answer." }, "intake_key": { "type": "string", "description": "The question on the intake that the answer fills in, by its key. The intake asks it with this answer already filled in." }, "value": { "type": "string", "description": "The answer, as the intake stores it: an option's value for a choice, the words otherwise." }, "heard_as": { "type": "string", "description": "What the person actually said, word for word, for example `about ninety thousand`. The client sees this beside the filled-in answer." }, "source": { "type": "string", "description": "Where BrokerPlus heard it: `call`, `email`, or `meeting`." }, "communication_id": { "nullable": true, "description": "The call, email, or meeting that the answer came from. Read it with `GET /v1/communications/{id}`. Null when that record was removed.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the person said it. The newest answer to a question wins." }, "applied_at": { "nullable": true, "description": "When the answer filled in an intake sent to the person. Null while it waits for the next intake.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus read the answer off the call or email." }, "updated_at": { "type": "string", "description": "When the answer last changed." } }, "required": [ "object", "id", "contact_id", "intake_key", "value", "heard_as", "source", "communication_id", "occurred_at", "applied_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` or `pending` is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes": { "get": { "operationId": "listIntakes", "summary": "List intakes", "description": "One row per client application, newest first. `updated_since` pages on when each last changed, so a daily job can ask for what moved. Asking by `contact_id` answers an intake the contact is a co-applicant on as well as one in their own name.", "tags": [ "Intakes" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only intakes on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only intakes this contact was asked to fill in." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake", "description": "The type of this record. Always `intake`.", "type": "string", "enum": [ "intake" ] }, "id": { "type": "string", "description": "Stable identifier." }, "contact_id": { "type": "string", "description": "The client who was asked to fill it in." }, "deal_id": { "nullable": true, "description": "The deal it belongs to. Null for an intake sent before a deal exists.", "type": "string" }, "co_applicant_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Everyone else asked to fill in the same intake." }, "status": { "type": "string", "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`. A new intake starts `in_progress`." }, "delivered_at": { "nullable": true, "description": "When the client first had it: an email we sent, or them opening the link. Null means neither.", "type": "string" }, "first_opened_at": { "nullable": true, "description": "When the client first opened it.", "type": "string" }, "last_activity_at": { "type": "string", "description": "The last thing the client did in it." }, "submitted_at": { "nullable": true, "description": "When the client sent it back.", "type": "string" }, "approved_at": { "nullable": true, "description": "When a broker accepted what came back.", "type": "string" }, "needs_changes_at": { "nullable": true, "description": "When a broker last sent it back to the client for changes. Null if they never did.", "type": "string" }, "last_reminder_at": { "nullable": true, "description": "When the client was last reminded to finish it. Null before the first.", "type": "string" }, "reminder_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reminders the client has had." }, "status_note": { "nullable": true, "description": "The broker's note to the client beside the status, in plain words. Null when there is none.", "type": "string" }, "status_note_updated_at": { "nullable": true, "description": "When the broker last changed `status_note`.", "type": "string" }, "portal_type": { "type": "string", "enum": [ "full_intake", "intake_only", "intake_docs", "intake_signing", "doc_upload", "doc_signing", "upload_signing" ], "description": "What the client is asked for: questions, documents, signatures, or a mix. `intake_only` is questions only; `full_intake` is all three." }, "application_id": { "nullable": true, "description": "The mortgage application on the deal that it collects for. Null when it names none.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker who sent it." }, "template_id": { "type": "string", "description": "The intake template it was sent from." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "When it last changed." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do. Answers save as the client types, before this.", "type": "string" }, "answered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant has answered." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant is asked. It can change as they answer, because some answers add or remove questions." }, "unanswered": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "section_label": { "type": "string", "description": "The section name a broker sees, e.g. `Income`." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, the same key as on the answers endpoint." }, "label": { "type": "string", "description": "The question name a broker sees, e.g. `Date of birth`." } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The required questions in this section that have no answer yet." } }, "required": [ "section_key", "section_label", "questions" ], "additionalProperties": false }, "description": "Each section that still has a required question with no answer, in the order the client meets them." } }, "required": [ "contact_id", "name", "role", "submitted_at", "answered", "total", "unanswered" ], "additionalProperties": false }, "description": "Progress for each applicant, the primary first. An intake that asks for documents only has no questions, so its totals are 0." } }, "required": [ "object", "id", "contact_id", "deal_id", "co_applicant_contact_ids", "status", "delivered_at", "first_opened_at", "last_activity_at", "submitted_at", "approved_at", "needs_changes_at", "last_reminder_at", "reminder_count", "status_note", "status_note_updated_at", "portal_type", "application_id", "broker_user_id", "template_id", "created_at", "updated_at", "applicants" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createIntake", "summary": "Ask a client to fill in an intake", "description": "Creates an intake for one client, with or without a deal. `delivery` of `link` returns the client's link and sends nothing. `delivery` of `email` creates the intake and emails each applicant their link now, from the broker's connected mailbox. It answers `412 EMAIL_NOT_CONNECTED` if the broker has no mailbox connected. A key with the `no_sending` limit cannot use `email`, and neither can a key whose brokerage's automation policy does not allow messages to clients to be asked for this way (`403 POLICY_BLOCKED`). A client who already has an open intake answers `409 DUPLICATE_INTAKE`.", "tags": [ "Intakes" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The client to ask. They must already be a contact." }, "deal_id": { "description": "The deal this intake belongs to. Leave it out for a new client with no deal yet.", "nullable": true, "type": "string" }, "co_applicant_contact_ids": { "description": "Other clients on the same application. Each one gets their own link.", "maxItems": 10, "type": "array", "items": { "type": "string" } }, "delivery": { "description": "`link` returns the link and sends nothing, which is the default. `email` has BrokerPlus send it from the broker's own mailbox, and needs that mailbox connected.", "type": "string", "enum": [ "link", "email" ] } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake", "description": "The type of this record. Always `intake`.", "type": "string", "enum": [ "intake" ] }, "id": { "type": "string", "description": "Stable identifier." }, "contact_id": { "type": "string", "description": "The client who was asked to fill it in." }, "deal_id": { "nullable": true, "description": "The deal it belongs to. Null for an intake sent before a deal exists.", "type": "string" }, "co_applicant_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Everyone else asked to fill in the same intake." }, "status": { "type": "string", "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`. A new intake starts `in_progress`." }, "delivered_at": { "nullable": true, "description": "When the client first had it: an email we sent, or them opening the link. Null means neither.", "type": "string" }, "first_opened_at": { "nullable": true, "description": "When the client first opened it.", "type": "string" }, "last_activity_at": { "type": "string", "description": "The last thing the client did in it." }, "submitted_at": { "nullable": true, "description": "When the client sent it back.", "type": "string" }, "approved_at": { "nullable": true, "description": "When a broker accepted what came back.", "type": "string" }, "needs_changes_at": { "nullable": true, "description": "When a broker last sent it back to the client for changes. Null if they never did.", "type": "string" }, "last_reminder_at": { "nullable": true, "description": "When the client was last reminded to finish it. Null before the first.", "type": "string" }, "reminder_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reminders the client has had." }, "status_note": { "nullable": true, "description": "The broker's note to the client beside the status, in plain words. Null when there is none.", "type": "string" }, "status_note_updated_at": { "nullable": true, "description": "When the broker last changed `status_note`.", "type": "string" }, "portal_type": { "type": "string", "enum": [ "full_intake", "intake_only", "intake_docs", "intake_signing", "doc_upload", "doc_signing", "upload_signing" ], "description": "What the client is asked for: questions, documents, signatures, or a mix. `intake_only` is questions only; `full_intake` is all three." }, "application_id": { "nullable": true, "description": "The mortgage application on the deal that it collects for. Null when it names none.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker who sent it." }, "template_id": { "type": "string", "description": "The intake template it was sent from." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "When it last changed." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do. Answers save as the client types, before this.", "type": "string" }, "answered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant has answered." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant is asked. It can change as they answer, because some answers add or remove questions." }, "unanswered": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "section_label": { "type": "string", "description": "The section name a broker sees, e.g. `Income`." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, the same key as on the answers endpoint." }, "label": { "type": "string", "description": "The question name a broker sees, e.g. `Date of birth`." } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The required questions in this section that have no answer yet." } }, "required": [ "section_key", "section_label", "questions" ], "additionalProperties": false }, "description": "Each section that still has a required question with no answer, in the order the client meets them." } }, "required": [ "contact_id", "name", "role", "submitted_at", "answered", "total", "unanswered" ], "additionalProperties": false }, "description": "Progress for each applicant, the primary first. An intake that asks for documents only has no questions, so its totals are 0." }, "url": { "nullable": true, "description": "The link for the client, when you asked for `link`. Null when you asked BrokerPlus to email it.", "type": "string" }, "url_expires_at": { "nullable": true, "description": "When that link stops working.", "type": "string" } }, "required": [ "object", "id", "contact_id", "deal_id", "co_applicant_contact_ids", "status", "delivered_at", "first_opened_at", "last_activity_at", "submitted_at", "approved_at", "needs_changes_at", "last_reminder_at", "reminder_count", "status_note", "status_note_updated_at", "portal_type", "application_id", "broker_user_id", "template_id", "created_at", "updated_at", "applicants", "url", "url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}": { "get": { "operationId": "getIntake", "summary": "Retrieve an intake", "description": "A single intake by id, with each applicant's progress.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake", "description": "The type of this record. Always `intake`.", "type": "string", "enum": [ "intake" ] }, "id": { "type": "string", "description": "Stable identifier." }, "contact_id": { "type": "string", "description": "The client who was asked to fill it in." }, "deal_id": { "nullable": true, "description": "The deal it belongs to. Null for an intake sent before a deal exists.", "type": "string" }, "co_applicant_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Everyone else asked to fill in the same intake." }, "status": { "type": "string", "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`. A new intake starts `in_progress`." }, "delivered_at": { "nullable": true, "description": "When the client first had it: an email we sent, or them opening the link. Null means neither.", "type": "string" }, "first_opened_at": { "nullable": true, "description": "When the client first opened it.", "type": "string" }, "last_activity_at": { "type": "string", "description": "The last thing the client did in it." }, "submitted_at": { "nullable": true, "description": "When the client sent it back.", "type": "string" }, "approved_at": { "nullable": true, "description": "When a broker accepted what came back.", "type": "string" }, "needs_changes_at": { "nullable": true, "description": "When a broker last sent it back to the client for changes. Null if they never did.", "type": "string" }, "last_reminder_at": { "nullable": true, "description": "When the client was last reminded to finish it. Null before the first.", "type": "string" }, "reminder_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reminders the client has had." }, "status_note": { "nullable": true, "description": "The broker's note to the client beside the status, in plain words. Null when there is none.", "type": "string" }, "status_note_updated_at": { "nullable": true, "description": "When the broker last changed `status_note`.", "type": "string" }, "portal_type": { "type": "string", "enum": [ "full_intake", "intake_only", "intake_docs", "intake_signing", "doc_upload", "doc_signing", "upload_signing" ], "description": "What the client is asked for: questions, documents, signatures, or a mix. `intake_only` is questions only; `full_intake` is all three." }, "application_id": { "nullable": true, "description": "The mortgage application on the deal that it collects for. Null when it names none.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker who sent it." }, "template_id": { "type": "string", "description": "The intake template it was sent from." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "When it last changed." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do. Answers save as the client types, before this.", "type": "string" }, "answered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant has answered." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant is asked. It can change as they answer, because some answers add or remove questions." }, "unanswered": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "section_label": { "type": "string", "description": "The section name a broker sees, e.g. `Income`." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, the same key as on the answers endpoint." }, "label": { "type": "string", "description": "The question name a broker sees, e.g. `Date of birth`." } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The required questions in this section that have no answer yet." } }, "required": [ "section_key", "section_label", "questions" ], "additionalProperties": false }, "description": "Each section that still has a required question with no answer, in the order the client meets them." } }, "required": [ "contact_id", "name", "role", "submitted_at", "answered", "total", "unanswered" ], "additionalProperties": false }, "description": "Progress for each applicant, the primary first. An intake that asks for documents only has no questions, so its totals are 0." } }, "required": [ "object", "id", "contact_id", "deal_id", "co_applicant_contact_ids", "status", "delivered_at", "first_opened_at", "last_activity_at", "submitted_at", "approved_at", "needs_changes_at", "last_reminder_at", "reminder_count", "status_note", "status_note_updated_at", "portal_type", "application_id", "broker_user_id", "template_id", "created_at", "updated_at", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/answers": { "get": { "operationId": "getIntakeAnswers", "summary": "Read an intake's answers", "description": "Every question each applicant is asked, grouped by section, with the answer as it stands now. Answers save as the client types, so an intake that is not submitted yet shows what the client has filled in so far, the same as the broker sees in BrokerPlus. Check each applicant's `submitted_at` to know if the answers are final. The SIN is never returned.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "intake_id": { "type": "string", "description": "The intake these answers belong to." }, "status": { "type": "string", "description": "The intake status, the same value as on `GET /intakes/{id}`." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do.", "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "label": { "type": "string", "description": "The section name a broker sees." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, e.g. `date_of_birth`." }, "label": { "type": "string", "description": "The question name a broker sees." }, "kind": { "type": "string", "enum": [ "field", "repeater", "consent", "signature" ], "description": "`field` is one answer. `repeater` is a list the client can add rows to, such as jobs or properties. `consent` is a box the client ticked. `signature` is the brokerage's consent form, signed." }, "required": { "type": "boolean", "description": "Whether the client must answer it before they can send the intake." }, "answered": { "type": "boolean", "description": "Whether it has an answer. For `consent` and `signature`, whether the client gave it." }, "value": { "description": "The answer as BrokerPlus stores it. A `field` is a string, a number, a list of strings, or an address object. A `repeater` is a list of objects keyed by question key. A `consent` or `signature` is `true` or `false`. Null when there is no answer, and when `withheld` is `true`." }, "value_label": { "nullable": true, "description": "For a choice question, the option a broker sees, e.g. `Purchase` for the stored value `3`. Null otherwise.", "type": "string" }, "withheld": { "type": "boolean", "description": "`true` for the SIN. The API never returns it. `answered` tells you if the client gave one. The number is on the applicant profile in BrokerPlus." } }, "required": [ "key", "label", "kind", "required", "answered", "value", "value_label", "withheld" ], "additionalProperties": false }, "description": "Every question this applicant is asked in this section, answered or not." } }, "required": [ "key", "label", "answers" ], "additionalProperties": false }, "description": "The sections this applicant is asked, in the order the client fills them in." } }, "required": [ "contact_id", "name", "role", "submitted_at", "sections" ], "additionalProperties": false }, "description": "One entry per applicant, the primary first. Questions the whole household shares, such as the property, are on the primary only." } }, "required": [ "intake_id", "status", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/approve": { "post": { "operationId": "approveIntake", "summary": "Approve an intake", "description": "Accepts what the client sent, the same as **Approve** on the intake in BrokerPlus. BrokerPlus builds the submission package and locks the answers. The client gets no message. The intake must be `submitted` or `needs_changes`.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake", "description": "The type of this record. Always `intake`.", "type": "string", "enum": [ "intake" ] }, "id": { "type": "string", "description": "Stable identifier." }, "contact_id": { "type": "string", "description": "The client who was asked to fill it in." }, "deal_id": { "nullable": true, "description": "The deal it belongs to. Null for an intake sent before a deal exists.", "type": "string" }, "co_applicant_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Everyone else asked to fill in the same intake." }, "status": { "type": "string", "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`. A new intake starts `in_progress`." }, "delivered_at": { "nullable": true, "description": "When the client first had it: an email we sent, or them opening the link. Null means neither.", "type": "string" }, "first_opened_at": { "nullable": true, "description": "When the client first opened it.", "type": "string" }, "last_activity_at": { "type": "string", "description": "The last thing the client did in it." }, "submitted_at": { "nullable": true, "description": "When the client sent it back.", "type": "string" }, "approved_at": { "nullable": true, "description": "When a broker accepted what came back.", "type": "string" }, "needs_changes_at": { "nullable": true, "description": "When a broker last sent it back to the client for changes. Null if they never did.", "type": "string" }, "last_reminder_at": { "nullable": true, "description": "When the client was last reminded to finish it. Null before the first.", "type": "string" }, "reminder_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reminders the client has had." }, "status_note": { "nullable": true, "description": "The broker's note to the client beside the status, in plain words. Null when there is none.", "type": "string" }, "status_note_updated_at": { "nullable": true, "description": "When the broker last changed `status_note`.", "type": "string" }, "portal_type": { "type": "string", "enum": [ "full_intake", "intake_only", "intake_docs", "intake_signing", "doc_upload", "doc_signing", "upload_signing" ], "description": "What the client is asked for: questions, documents, signatures, or a mix. `intake_only` is questions only; `full_intake` is all three." }, "application_id": { "nullable": true, "description": "The mortgage application on the deal that it collects for. Null when it names none.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker who sent it." }, "template_id": { "type": "string", "description": "The intake template it was sent from." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "When it last changed." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do. Answers save as the client types, before this.", "type": "string" }, "answered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant has answered." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant is asked. It can change as they answer, because some answers add or remove questions." }, "unanswered": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "section_label": { "type": "string", "description": "The section name a broker sees, e.g. `Income`." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, the same key as on the answers endpoint." }, "label": { "type": "string", "description": "The question name a broker sees, e.g. `Date of birth`." } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The required questions in this section that have no answer yet." } }, "required": [ "section_key", "section_label", "questions" ], "additionalProperties": false }, "description": "Each section that still has a required question with no answer, in the order the client meets them." } }, "required": [ "contact_id", "name", "role", "submitted_at", "answered", "total", "unanswered" ], "additionalProperties": false }, "description": "Progress for each applicant, the primary first. An intake that asks for documents only has no questions, so its totals are 0." } }, "required": [ "object", "id", "contact_id", "deal_id", "co_applicant_contact_ids", "status", "delivered_at", "first_opened_at", "last_activity_at", "submitted_at", "approved_at", "needs_changes_at", "last_reminder_at", "reminder_count", "status_note", "status_note_updated_at", "portal_type", "application_id", "broker_user_id", "template_id", "created_at", "updated_at", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The intake is not `submitted` or `needs_changes` (WRONG_STATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/request-changes": { "post": { "operationId": "requestIntakeChanges", "summary": "Ask the client to change answers or send new files", "description": "Reopens the answers you name in `changes`, and refuses the files you name in `uploads`, now. BrokerPlus **emails the client** a link to fix them, with your `message` and a comment on each answer or file, the same as a change request sent on the intake in BrokerPlus. A refused file is replaced when the client sends a new one. The intake moves to `needs_changes`, and the response is the intake. The client must have submitted the intake first. A key with the `no_sending` limit cannot use this endpoint.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The note the client reads in the email, e.g. what to fix and why." }, "changes": { "description": "The answers to reopen. Each one shows as a request in the client's portal, with your comment.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "question_key": { "type": "string", "minLength": 1, "description": "The `key` of the question to reopen, from `GET /intakes/{id}/answers`." }, "contact_id": { "description": "The applicant who must change it. Omit it for the client the intake is in the name of.", "type": "string" }, "comment": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What is wrong with this answer, in words the client reads." } }, "required": [ "question_key", "comment" ], "additionalProperties": false } }, "uploads": { "description": "Files to refuse. The client who sent each one is asked for a new copy, with your comment. Send `changes`, `uploads`, or both.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "upload_id": { "type": "string", "minLength": 1, "description": "The `id` of a file the client sent, from `GET /intakes/{id}/uploads`, to refuse." }, "comment": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What is wrong with the file, in words the client reads, e.g. `This page is cut off`." } }, "required": [ "upload_id", "comment" ], "additionalProperties": false } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake", "description": "The type of this record. Always `intake`.", "type": "string", "enum": [ "intake" ] }, "id": { "type": "string", "description": "Stable identifier." }, "contact_id": { "type": "string", "description": "The client who was asked to fill it in." }, "deal_id": { "nullable": true, "description": "The deal it belongs to. Null for an intake sent before a deal exists.", "type": "string" }, "co_applicant_contact_ids": { "type": "array", "items": { "type": "string" }, "description": "Everyone else asked to fill in the same intake." }, "status": { "type": "string", "description": "`in_progress`, `submitted`, `approved`, or `needs_changes`. A new intake starts `in_progress`." }, "delivered_at": { "nullable": true, "description": "When the client first had it: an email we sent, or them opening the link. Null means neither.", "type": "string" }, "first_opened_at": { "nullable": true, "description": "When the client first opened it.", "type": "string" }, "last_activity_at": { "type": "string", "description": "The last thing the client did in it." }, "submitted_at": { "nullable": true, "description": "When the client sent it back.", "type": "string" }, "approved_at": { "nullable": true, "description": "When a broker accepted what came back.", "type": "string" }, "needs_changes_at": { "nullable": true, "description": "When a broker last sent it back to the client for changes. Null if they never did.", "type": "string" }, "last_reminder_at": { "nullable": true, "description": "When the client was last reminded to finish it. Null before the first.", "type": "string" }, "reminder_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reminders the client has had." }, "status_note": { "nullable": true, "description": "The broker's note to the client beside the status, in plain words. Null when there is none.", "type": "string" }, "status_note_updated_at": { "nullable": true, "description": "When the broker last changed `status_note`.", "type": "string" }, "portal_type": { "type": "string", "enum": [ "full_intake", "intake_only", "intake_docs", "intake_signing", "doc_upload", "doc_signing", "upload_signing" ], "description": "What the client is asked for: questions, documents, signatures, or a mix. `intake_only` is questions only; `full_intake` is all three." }, "application_id": { "nullable": true, "description": "The mortgage application on the deal that it collects for. Null when it names none.", "type": "string" }, "broker_user_id": { "type": "string", "description": "The broker who sent it." }, "template_id": { "type": "string", "description": "The intake template it was sent from." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "When it last changed." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "submitted_at": { "nullable": true, "description": "When this applicant sent their part. Null until they do. Answers save as the client types, before this.", "type": "string" }, "answered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant has answered." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Required questions this applicant is asked. It can change as they answer, because some answers add or remove questions." }, "unanswered": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "description": "Stable key of the section, e.g. `income`." }, "section_label": { "type": "string", "description": "The section name a broker sees, e.g. `Income`." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the question, the same key as on the answers endpoint." }, "label": { "type": "string", "description": "The question name a broker sees, e.g. `Date of birth`." } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The required questions in this section that have no answer yet." } }, "required": [ "section_key", "section_label", "questions" ], "additionalProperties": false }, "description": "Each section that still has a required question with no answer, in the order the client meets them." } }, "required": [ "contact_id", "name", "role", "submitted_at", "answered", "total", "unanswered" ], "additionalProperties": false }, "description": "Progress for each applicant, the primary first. An intake that asks for documents only has no questions, so its totals are 0." } }, "required": [ "object", "id", "contact_id", "deal_id", "co_applicant_contact_ids", "status", "delivered_at", "first_opened_at", "last_activity_at", "submitted_at", "approved_at", "needs_changes_at", "last_reminder_at", "reminder_count", "status_note", "status_note_updated_at", "portal_type", "application_id", "broker_user_id", "template_id", "created_at", "updated_at", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The client has not submitted the intake yet (NOT_SUBMITTED), or it is no longer waiting on a review (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "A `question_key` is not on this intake, a `contact_id` is not an applicant on it, or an `upload_id` is not a live file on it (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/items": { "get": { "operationId": "listIntakeItems", "summary": "List what a client was asked for", "description": "Every item on the client's portal other than a question: each document, form to sign, consent, identity check and down payment source, in the order the client sees them. Each item lists the applicants it is for, with what each one did about it and the files they sent. The questions and their answers are on `GET /intakes/{id}/answers`. For only what the client still owes on a deal, use `GET /deals/{id}/document-requests`.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_item", "description": "The type of this record. Always `intake_item`.", "type": "string", "enum": [ "intake_item" ] }, "key": { "type": "string", "description": "Stable key of the item on this intake. Use it in the item routes." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "kind": { "type": "string", "enum": [ "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` give a consent, `identity_verification` verify who they are." }, "label": { "type": "string", "description": "What the client was asked for, in the words they saw." }, "description": { "nullable": true, "description": "The detail the client sees under the label. Null if none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` the client must do it. `optional` they may skip it. `required_with_dismissible_reason` they may skip it if they say why." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type asked for, from `GET /v1/document-types`. Null otherwise.", "type": "string" }, "added_by_broker": { "type": "boolean", "description": "`true` when the broker asked for it after the intake was sent. `false` when it came with the intake." }, "added_at": { "nullable": true, "description": "When the broker added it. Null when it came with the intake.", "type": "string" }, "waiting_on_intake": { "type": "boolean", "description": "`true` when the client has not seen it yet, because it waits until they finish their application." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "doc_status": { "nullable": true, "description": "For a document, where its checks are, the same values as `status` on an upload. Null when nothing was sent.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put this applicant's item in: `pending`, `review`, or `verified`. Null when the broker has not moved it.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the applicant marked it done. Null until they do.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the applicant said they cannot provide it. Null if they did not.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "Why the applicant cannot provide it, in their words.", "type": "string" }, "uploads": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at" ], "additionalProperties": false }, "description": "The files this applicant sent for it, newest first. A file the client replaced is not listed." } }, "required": [ "contact_id", "name", "role", "doc_status", "broker_stage", "submitted_at", "dismissed_at", "dismiss_reason", "uploads" ], "additionalProperties": false }, "description": "One entry for each applicant the item is for, the primary first. An item that only one applicant is asked, or that an earlier answer ruled out, lists only who is asked." } }, "required": [ "object", "key", "intake_id", "kind", "label", "description", "required_mode", "document_type", "added_by_broker", "added_at", "waiting_on_intake", "applicants" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/items/{key}": { "get": { "operationId": "getIntakeItem", "summary": "Retrieve one item a client was asked for", "description": "One item by its `key`, with each applicant's state and files.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_item", "description": "The type of this record. Always `intake_item`.", "type": "string", "enum": [ "intake_item" ] }, "key": { "type": "string", "description": "Stable key of the item on this intake. Use it in the item routes." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "kind": { "type": "string", "enum": [ "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` give a consent, `identity_verification` verify who they are." }, "label": { "type": "string", "description": "What the client was asked for, in the words they saw." }, "description": { "nullable": true, "description": "The detail the client sees under the label. Null if none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` the client must do it. `optional` they may skip it. `required_with_dismissible_reason` they may skip it if they say why." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type asked for, from `GET /v1/document-types`. Null otherwise.", "type": "string" }, "added_by_broker": { "type": "boolean", "description": "`true` when the broker asked for it after the intake was sent. `false` when it came with the intake." }, "added_at": { "nullable": true, "description": "When the broker added it. Null when it came with the intake.", "type": "string" }, "waiting_on_intake": { "type": "boolean", "description": "`true` when the client has not seen it yet, because it waits until they finish their application." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "doc_status": { "nullable": true, "description": "For a document, where its checks are, the same values as `status` on an upload. Null when nothing was sent.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put this applicant's item in: `pending`, `review`, or `verified`. Null when the broker has not moved it.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the applicant marked it done. Null until they do.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the applicant said they cannot provide it. Null if they did not.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "Why the applicant cannot provide it, in their words.", "type": "string" }, "uploads": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at" ], "additionalProperties": false }, "description": "The files this applicant sent for it, newest first. A file the client replaced is not listed." } }, "required": [ "contact_id", "name", "role", "doc_status", "broker_stage", "submitted_at", "dismissed_at", "dismiss_reason", "uploads" ], "additionalProperties": false }, "description": "One entry for each applicant the item is for, the primary first. An item that only one applicant is asked, or that an earlier answer ruled out, lists only who is asked." } }, "required": [ "object", "key", "intake_id", "kind", "label", "description", "required_mode", "document_type", "added_by_broker", "added_at", "waiting_on_intake", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/items/{key}/stage": { "post": { "operationId": "moveIntakeItemStage", "summary": "Move an item on the broker's board", "description": "Puts one applicant's item in a tray on the broker's document board, as a drag on the board does. Send `stage` `verified` to accept it. Use it for an item with no file, for example a document the broker already has. To move a file the client sent, use `POST /intakes/{id}/uploads/{uploadId}/stage`. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The applicant whose item to move, from `applicants` on the item." }, "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "The tray to put the item in on the broker's board. `verified` marks it accepted. `pending` and `review` take it back." } }, "required": [ "contact_id", "stage" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_item", "description": "The type of this record. Always `intake_item`.", "type": "string", "enum": [ "intake_item" ] }, "key": { "type": "string", "description": "Stable key of the item on this intake. Use it in the item routes." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "kind": { "type": "string", "enum": [ "doc_request", "signing_form", "down_payment_source", "consent_attestation", "identity_verification" ], "description": "What the client is asked to do: `doc_request` send a document, `signing_form` sign a form, `down_payment_source` say where the down payment comes from, `consent_attestation` give a consent, `identity_verification` verify who they are." }, "label": { "type": "string", "description": "What the client was asked for, in the words they saw." }, "description": { "nullable": true, "description": "The detail the client sees under the label. Null if none.", "type": "string" }, "required_mode": { "type": "string", "enum": [ "required", "optional", "required_with_dismissible_reason" ], "description": "`required` the client must do it. `optional` they may skip it. `required_with_dismissible_reason` they may skip it if they say why." }, "document_type": { "nullable": true, "description": "For a `doc_request`, the document type asked for, from `GET /v1/document-types`. Null otherwise.", "type": "string" }, "added_by_broker": { "type": "boolean", "description": "`true` when the broker asked for it after the intake was sent. `false` when it came with the intake." }, "added_at": { "nullable": true, "description": "When the broker added it. Null when it came with the intake.", "type": "string" }, "waiting_on_intake": { "type": "boolean", "description": "`true` when the client has not seen it yet, because it waits until they finish their application." }, "applicants": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The applicant." }, "name": { "type": "string", "description": "The applicant's name, as it was typed when the intake was sent." }, "role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "`primary` for the client the intake is in the name of. `co_applicant` for everybody else on it." }, "doc_status": { "nullable": true, "description": "For a document, where its checks are, the same values as `status` on an upload. Null when nothing was sent.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put this applicant's item in: `pending`, `review`, or `verified`. Null when the broker has not moved it.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the applicant marked it done. Null until they do.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When the applicant said they cannot provide it. Null if they did not.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "Why the applicant cannot provide it, in their words.", "type": "string" }, "uploads": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at" ], "additionalProperties": false }, "description": "The files this applicant sent for it, newest first. A file the client replaced is not listed." } }, "required": [ "contact_id", "name", "role", "doc_status", "broker_stage", "submitted_at", "dismissed_at", "dismiss_reason", "uploads" ], "additionalProperties": false }, "description": "One entry for each applicant the item is for, the primary first. An item that only one applicant is asked, or that an earlier answer ruled out, lists only who is asked." } }, "required": [ "object", "key", "intake_id", "kind", "label", "description", "required_mode", "document_type", "added_by_broker", "added_at", "waiting_on_intake", "applicants" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The contact is not an applicant this item is for (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/uploads": { "get": { "operationId": "listIntakeUploads", "summary": "List the files a client sent", "description": "Every file the client sent through their portal, newest first. A file the client replaced is not listed. A file becomes a deal document only when the broker verifies it.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/uploads/{uploadId}": { "get": { "operationId": "getIntakeUpload", "summary": "Retrieve a file a client sent", "description": "The file's metadata plus a signed download URL valid for five minutes. Follow it, do not store it.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." }, "download_url": { "type": "string", "description": "Short-lived signed URL. Expires in 5 minutes - fetch it, do not store it." }, "download_url_expires_at": { "type": "string", "description": "When that URL stops working." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at", "download_url", "download_url_expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/uploads/{uploadId}/stage": { "post": { "operationId": "moveIntakeUploadStage", "summary": "Accept a file a client sent", "description": "Moves the file to a tray on the broker's document board, as a drag on the board does. Send `stage` `verified` to accept it: BrokerPlus reads it and copies it to the deal's documents, and `document_id` then names the copy. Nothing goes to the client. To refuse a file and ask the client for a new one, use `POST /intakes/{id}/request-changes` with `uploads`.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "pending", "review", "verified" ], "description": "The tray to move the upload to. `verified` accepts it: BrokerPlus reads it and copies it to the deal's documents. `pending` and `review` take it back. To refuse a file and ask the client for a new one, use `POST /v1/intakes/{id}/request-changes`." }, "folder": { "description": "The folder for a verified upload, for example `income`. Only with `stage` `verified`.", "type": "string", "enum": [ "income", "self_employed", "down_payment", "property", "identity_status", "credit_history", "life_events", "compliance", "signed", "other", "unsorted" ] } }, "required": [ "stage" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_upload", "description": "The type of this record. Always `intake_upload`.", "type": "string", "enum": [ "intake_upload" ] }, "id": { "type": "string", "description": "Stable identifier for the upload." }, "intake_id": { "type": "string", "description": "The intake the client sent it through." }, "item_key": { "nullable": true, "description": "The `key` of the item it answers, from `GET /v1/intakes/{id}/items`. Null for a loose upload.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant who sent it." }, "file_name": { "type": "string", "description": "The file name as the client sent it." }, "display_name": { "nullable": true, "description": "The name BrokerPlus or the broker gave the file, e.g. `2025 T4 - Jane Smith.pdf`. Null if none.", "type": "string" }, "mime_type": { "type": "string", "description": "The file type, e.g. `application/pdf`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size in bytes." }, "page_count": { "nullable": true, "description": "How many pages it has. Null until BrokerPlus has read it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "description": "Where the checks are: `uploaded`, `classified`, `extracting`, `extracted` and `qa_running` while BrokerPlus reads it, then `verified`, `needs_review`, or `rejected`. `rejected` means the checks refused it." }, "classification": { "nullable": true, "description": "The document type BrokerPlus read it as, a `code` from `GET /v1/document-types`. Null until read.", "type": "string" }, "broker_stage": { "nullable": true, "description": "The tray the broker put it in: `pending`, `review`, or `verified`. Null when the broker has not moved it, so it sits where its checks put it.", "type": "string" }, "verified_folder": { "nullable": true, "description": "The folder of a verified upload, e.g. `income`, or `unsorted`. Null when it follows its type.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "What the client wrote to explain a problem the checks found. Null if they wrote nothing.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document it became when it was verified, for `GET /v1/documents/{id}`. Null before that.", "type": "string" }, "uploaded_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "When it last changed." } }, "required": [ "object", "id", "intake_id", "item_key", "contact_id", "file_name", "display_name", "mime_type", "file_size", "page_count", "status", "classification", "broker_stage", "verified_folder", "borrower_rationale", "document_id", "uploaded_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/flags": { "get": { "operationId": "listIntakeFlags", "summary": "List what the checks raised on an intake", "description": "The flags BrokerPlus's checks raised on a client's intake, the most serious first. A flag with `audience` `never_disclose` is for the broker only: never pass it on to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "resolved", "overridden", "stale" ] }, "description": "`active`, `resolved`, `overridden`, or `stale`. Any other value gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_flag", "description": "The type of this record. Always `intake_flag`.", "type": "string", "enum": [ "intake_flag" ] }, "id": { "type": "string", "description": "Stable identifier for the flag." }, "intake_id": { "type": "string", "description": "The intake it was raised on." }, "contact_id": { "nullable": true, "description": "The applicant it concerns. Null when it concerns the household or the deal as a whole.", "type": "string" }, "kind": { "type": "string", "enum": [ "recon_flag", "field_mismatch", "broker_only" ], "description": "What raised it: `recon_flag` a check across the file, `field_mismatch` an answer that disagrees with a document, `broker_only` a note for the broker that the client never sees." }, "rule_name": { "type": "string", "description": "The name of the check that raised it." }, "severity": { "type": "string", "enum": [ "soft", "hard", "hard_stop", "suspicious" ], "description": "How serious it is: `soft` worth a look, `hard` needs an answer, `hard_stop` blocks the file, `suspicious` a sign the file may not be genuine." }, "audience": { "type": "string", "enum": [ "borrower", "broker", "both", "never_disclose" ], "description": "Who it is shown to. `never_disclose` is for the broker only and must never be passed on to the client." }, "title": { "type": "string", "description": "A short heading for the flag." }, "message": { "type": "string", "description": "What the check found, in plain words." }, "status": { "type": "string", "enum": [ "active", "resolved", "overridden", "stale" ], "description": "`active` while it stands, `resolved` once the file answers it, `overridden` when the broker set it aside, `stale` when the answers it was raised on changed." }, "upload_ids": { "type": "array", "items": { "type": "string" }, "description": "The uploads it points at, from `GET /v1/intakes/{id}/uploads`." }, "item_keys": { "type": "array", "items": { "type": "string" }, "description": "The items it points at, from `GET /v1/intakes/{id}/items`." }, "field_key": { "nullable": true, "description": "The intake answer it disagrees with, for a `field_mismatch`. Null otherwise.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "The client's own explanation, when they gave one. Null if none.", "type": "string" }, "overridden_by_user_id": { "nullable": true, "description": "The broker who overrode it. Null unless overridden.", "type": "string" }, "override_reason": { "nullable": true, "description": "Why the broker overrode it. Null unless overridden.", "type": "string" }, "overridden_at": { "nullable": true, "description": "When it was overridden (ISO 8601). Null unless overridden.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When the file answered it (ISO 8601). Null while it stands.", "type": "string" }, "created_at": { "type": "string", "description": "When it was raised (ISO 8601)." }, "updated_at": { "type": "string", "description": "When it last changed (ISO 8601)." } }, "required": [ "object", "id", "intake_id", "contact_id", "kind", "rule_name", "severity", "audience", "title", "message", "status", "upload_ids", "item_keys", "field_key", "borrower_rationale", "overridden_by_user_id", "override_reason", "overridden_at", "resolved_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/flags/{flagId}/override": { "post": { "operationId": "overrideIntakeFlag", "summary": "Set a flag aside", "description": "The broker's Override: the flag stops standing against the file, with the reason kept on it and in the audit log. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "flagId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Why the flag can be set aside, in at least 10 characters. It is kept on the flag and in the audit log." } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_flag", "description": "The type of this record. Always `intake_flag`.", "type": "string", "enum": [ "intake_flag" ] }, "id": { "type": "string", "description": "Stable identifier for the flag." }, "intake_id": { "type": "string", "description": "The intake it was raised on." }, "contact_id": { "nullable": true, "description": "The applicant it concerns. Null when it concerns the household or the deal as a whole.", "type": "string" }, "kind": { "type": "string", "enum": [ "recon_flag", "field_mismatch", "broker_only" ], "description": "What raised it: `recon_flag` a check across the file, `field_mismatch` an answer that disagrees with a document, `broker_only` a note for the broker that the client never sees." }, "rule_name": { "type": "string", "description": "The name of the check that raised it." }, "severity": { "type": "string", "enum": [ "soft", "hard", "hard_stop", "suspicious" ], "description": "How serious it is: `soft` worth a look, `hard` needs an answer, `hard_stop` blocks the file, `suspicious` a sign the file may not be genuine." }, "audience": { "type": "string", "enum": [ "borrower", "broker", "both", "never_disclose" ], "description": "Who it is shown to. `never_disclose` is for the broker only and must never be passed on to the client." }, "title": { "type": "string", "description": "A short heading for the flag." }, "message": { "type": "string", "description": "What the check found, in plain words." }, "status": { "type": "string", "enum": [ "active", "resolved", "overridden", "stale" ], "description": "`active` while it stands, `resolved` once the file answers it, `overridden` when the broker set it aside, `stale` when the answers it was raised on changed." }, "upload_ids": { "type": "array", "items": { "type": "string" }, "description": "The uploads it points at, from `GET /v1/intakes/{id}/uploads`." }, "item_keys": { "type": "array", "items": { "type": "string" }, "description": "The items it points at, from `GET /v1/intakes/{id}/items`." }, "field_key": { "nullable": true, "description": "The intake answer it disagrees with, for a `field_mismatch`. Null otherwise.", "type": "string" }, "borrower_rationale": { "nullable": true, "description": "The client's own explanation, when they gave one. Null if none.", "type": "string" }, "overridden_by_user_id": { "nullable": true, "description": "The broker who overrode it. Null unless overridden.", "type": "string" }, "override_reason": { "nullable": true, "description": "Why the broker overrode it. Null unless overridden.", "type": "string" }, "overridden_at": { "nullable": true, "description": "When it was overridden (ISO 8601). Null unless overridden.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When the file answered it (ISO 8601). Null while it stands.", "type": "string" }, "created_at": { "type": "string", "description": "When it was raised (ISO 8601)." }, "updated_at": { "type": "string", "description": "When it last changed (ISO 8601)." } }, "required": [ "object", "id", "intake_id", "contact_id", "kind", "rule_name", "severity", "audience", "title", "message", "status", "upload_ids", "item_keys", "field_key", "borrower_rationale", "overridden_by_user_id", "override_reason", "overridden_at", "resolved_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/stated-income-scope": { "get": { "operationId": "getIntakeStatedIncomeScope", "summary": "Read what the income calculation counts", "description": "The broker's choices on the stated income card: the dates the calculation counts, the bank statements and accounts left out, and the income the client declared. `accounts` lists every bank account on the client's statements. An intake the broker never changed reads with no dates and nothing left out.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "intake_id": { "type": "string", "description": "The intake." }, "date_range_start": { "nullable": true, "description": "The first day the income calculation counts, as `YYYY-MM-DD`. Null counts from the earliest statement.", "type": "string" }, "date_range_end": { "nullable": true, "description": "The last day the income calculation counts, as `YYYY-MM-DD`. Null counts to the latest statement.", "type": "string" }, "excluded_upload_ids": { "type": "array", "items": { "type": "string" }, "description": "Bank statements the broker took out of the calculation, by `id` from `GET /v1/intakes/{id}/uploads`. A statement BrokerPlus drops on its own because others cover its period is not listed here." }, "excluded_account_keys": { "type": "array", "items": { "type": "string" }, "description": "Bank accounts the broker took out of the calculation, by `account_key` from `accounts`." }, "declared_annual_income": { "nullable": true, "description": "The yearly income the client declared, in dollars, shown beside the calculated income. Null if none.", "type": "number" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_key": { "type": "string", "description": "Names the account in `excluded_account_keys`. The bank's name and the last 4 digits, joined by `|`." }, "institution_name": { "nullable": true, "description": "The bank. Null if the statement did not say.", "type": "string" }, "account_last4": { "nullable": true, "description": "The last 4 digits of the account number. The whole number is never on the API.", "type": "string" }, "excluded": { "type": "boolean", "description": "`true` if the broker took the account out of the calculation." } }, "required": [ "account_key", "institution_name", "account_last4", "excluded" ], "additionalProperties": false }, "description": "Every bank account on the client's statements, so you can leave one out." }, "updated_by_user_id": { "nullable": true, "description": "The broker who last changed the scope. Null if nobody has.", "type": "string" }, "updated_at": { "nullable": true, "description": "When the scope last changed. Null if nobody has changed it.", "type": "string" } }, "required": [ "intake_id", "date_range_start", "date_range_end", "excluded_upload_ids", "excluded_account_keys", "declared_annual_income", "accounts", "updated_by_user_id", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateIntakeStatedIncomeScope", "summary": "Change what the income calculation counts", "description": "Sets the dates, the statements and accounts left out, or the declared income, as the stated income card does. A field you leave out keeps its value. BrokerPlus then works the income out again, which takes a moment. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date_range_start": { "description": "The first day to count, as `YYYY-MM-DD`. Send null to count from the earliest statement.", "nullable": true, "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "date_range_end": { "description": "The last day to count, as `YYYY-MM-DD`. Send null to count to the latest statement.", "nullable": true, "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "excluded_upload_ids": { "description": "Every statement to leave out. This replaces the list: send `[]` to put them all back.", "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "excluded_account_keys": { "description": "Every account to leave out, by `account_key`. This replaces the list: send `[]` to put them all back.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } }, "declared_annual_income": { "description": "The yearly income the client declared, in dollars. Send null to clear.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100000000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "intake_id": { "type": "string", "description": "The intake." }, "date_range_start": { "nullable": true, "description": "The first day the income calculation counts, as `YYYY-MM-DD`. Null counts from the earliest statement.", "type": "string" }, "date_range_end": { "nullable": true, "description": "The last day the income calculation counts, as `YYYY-MM-DD`. Null counts to the latest statement.", "type": "string" }, "excluded_upload_ids": { "type": "array", "items": { "type": "string" }, "description": "Bank statements the broker took out of the calculation, by `id` from `GET /v1/intakes/{id}/uploads`. A statement BrokerPlus drops on its own because others cover its period is not listed here." }, "excluded_account_keys": { "type": "array", "items": { "type": "string" }, "description": "Bank accounts the broker took out of the calculation, by `account_key` from `accounts`." }, "declared_annual_income": { "nullable": true, "description": "The yearly income the client declared, in dollars, shown beside the calculated income. Null if none.", "type": "number" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_key": { "type": "string", "description": "Names the account in `excluded_account_keys`. The bank's name and the last 4 digits, joined by `|`." }, "institution_name": { "nullable": true, "description": "The bank. Null if the statement did not say.", "type": "string" }, "account_last4": { "nullable": true, "description": "The last 4 digits of the account number. The whole number is never on the API.", "type": "string" }, "excluded": { "type": "boolean", "description": "`true` if the broker took the account out of the calculation." } }, "required": [ "account_key", "institution_name", "account_last4", "excluded" ], "additionalProperties": false }, "description": "Every bank account on the client's statements, so you can leave one out." }, "updated_by_user_id": { "nullable": true, "description": "The broker who last changed the scope. Null if nobody has.", "type": "string" }, "updated_at": { "nullable": true, "description": "When the scope last changed. Null if nobody has changed it.", "type": "string" } }, "required": [ "intake_id", "date_range_start", "date_range_end", "excluded_upload_ids", "excluded_account_keys", "declared_annual_income", "accounts", "updated_by_user_id", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The start date is after the end date, or the body sets nothing (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "An `excluded_upload_ids` entry is not a file on this intake (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/transactions": { "get": { "operationId": "listIntakeTransactions", "summary": "List the transactions on a client's bank statements", "description": "Every transaction BrokerPlus read off the client's bank statements, newest first, with what it was read as and the broker's change, if any. This is the transactions list on the stated income card. An account number is only ever its last 4 digits.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text in the description, the bank's name, or an amount." }, { "name": "upload_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only transactions on this bank statement." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "description": "Only transactions the income calculation counts as this category." }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "description": "Only transactions the income calculation counts as this subcategory." }, { "name": "applicant_role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "primary", "co_applicant" ] }, "description": "`primary` or `co_applicant`: only that applicant's statements." }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only transactions on or after this day, as `YYYY-MM-DD`." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only transactions on or before this day, as `YYYY-MM-DD`." }, { "name": "excluded", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` for only the transactions the broker took out, `false` for only the ones counted." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_transaction", "description": "The type of this record. Always `intake_transaction`.", "type": "string", "enum": [ "intake_transaction" ] }, "id": { "type": "string", "description": "Stable identifier for the transaction, built from the statement, the day, the amount and the line. It contains `:`, so encode it in a path." }, "intake_id": { "type": "string", "description": "The intake." }, "upload_id": { "type": "string", "description": "The bank statement it is on. See `GET /v1/intakes/{id}/uploads/{uploadId}`." }, "applicant_role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "Whose statement it is." }, "date": { "type": "string", "description": "The day of the transaction, as `YYYY-MM-DD`." }, "amount": { "type": "number", "description": "The amount, in dollars. Always positive: `type` says which way the money went." }, "type": { "type": "string", "enum": [ "credit", "debit" ], "description": "`credit` money in, `debit` money out." }, "description": { "type": "string", "description": "The line as the bank printed it." }, "institution_name": { "nullable": true, "description": "The bank. Null if the statement did not say.", "type": "string" }, "account_last4": { "nullable": true, "description": "The last 4 digits of the account number. The whole number is never on the API.", "type": "string" }, "account_key": { "type": "string", "description": "The account, as `excluded_account_keys` on the stated income scope names it." }, "category": { "nullable": true, "description": "What BrokerPlus read the transaction as. Null if it could not tell.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The finer kind BrokerPlus read. Null if it could not tell.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "effective_category": { "nullable": true, "description": "The category the income calculation uses: the broker's, if they changed it, or else `category`.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "effective_subcategory": { "nullable": true, "description": "The subcategory the income calculation uses: the broker's, if they changed it, or else `subcategory`.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out of the income calculation." }, "override": { "nullable": true, "description": "The broker's change to the transaction. Null if they never changed it.", "type": "object", "properties": { "category": { "nullable": true, "description": "The category the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The subcategory the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out." }, "note": { "nullable": true, "description": "The broker's note on why. Null if none.", "type": "string" }, "overridden_at": { "type": "string", "description": "When the broker last changed it." }, "overridden_by_user_id": { "type": "string", "description": "The broker who last changed it." } }, "required": [ "category", "subcategory", "excluded", "note", "overridden_at", "overridden_by_user_id" ], "additionalProperties": false } }, "required": [ "object", "id", "intake_id", "upload_id", "applicant_role", "date", "amount", "type", "description", "institution_name", "account_last4", "account_key", "category", "subcategory", "effective_category", "effective_subcategory", "excluded", "override" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/transactions/override": { "post": { "operationId": "overrideIntakeTransactions", "summary": "Change how transactions count", "description": "Takes transactions out of the income calculation, puts them back, or changes their category, as the stated income card does for the rows the broker selects. A field you leave out keeps each transaction's own value. BrokerPlus then works the income out again and settles any flag about a transaction taken out. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_ids": { "minItems": 1, "maxItems": 2000, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The transactions to change, by `id` from `GET /v1/intakes/{id}/transactions`. At most 2000." }, "category": { "description": "Set the category. Send null to go back to what BrokerPlus read.", "nullable": true, "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "description": "Set the subcategory. Send null to go back to what BrokerPlus read.", "nullable": true, "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "description": "`true` takes the transactions out of the income calculation, `false` puts them back.", "type": "boolean" }, "note": { "description": "A note on why. Send null to clear.", "nullable": true, "type": "string", "maxLength": 2000 } }, "required": [ "transaction_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many transactions changed." }, "skipped_transaction_ids": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that are not transactions on this intake. Nothing was written for them." }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_transaction", "description": "The type of this record. Always `intake_transaction`.", "type": "string", "enum": [ "intake_transaction" ] }, "id": { "type": "string", "description": "Stable identifier for the transaction, built from the statement, the day, the amount and the line. It contains `:`, so encode it in a path." }, "intake_id": { "type": "string", "description": "The intake." }, "upload_id": { "type": "string", "description": "The bank statement it is on. See `GET /v1/intakes/{id}/uploads/{uploadId}`." }, "applicant_role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "Whose statement it is." }, "date": { "type": "string", "description": "The day of the transaction, as `YYYY-MM-DD`." }, "amount": { "type": "number", "description": "The amount, in dollars. Always positive: `type` says which way the money went." }, "type": { "type": "string", "enum": [ "credit", "debit" ], "description": "`credit` money in, `debit` money out." }, "description": { "type": "string", "description": "The line as the bank printed it." }, "institution_name": { "nullable": true, "description": "The bank. Null if the statement did not say.", "type": "string" }, "account_last4": { "nullable": true, "description": "The last 4 digits of the account number. The whole number is never on the API.", "type": "string" }, "account_key": { "type": "string", "description": "The account, as `excluded_account_keys` on the stated income scope names it." }, "category": { "nullable": true, "description": "What BrokerPlus read the transaction as. Null if it could not tell.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The finer kind BrokerPlus read. Null if it could not tell.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "effective_category": { "nullable": true, "description": "The category the income calculation uses: the broker's, if they changed it, or else `category`.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "effective_subcategory": { "nullable": true, "description": "The subcategory the income calculation uses: the broker's, if they changed it, or else `subcategory`.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out of the income calculation." }, "override": { "nullable": true, "description": "The broker's change to the transaction. Null if they never changed it.", "type": "object", "properties": { "category": { "nullable": true, "description": "The category the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The subcategory the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out." }, "note": { "nullable": true, "description": "The broker's note on why. Null if none.", "type": "string" }, "overridden_at": { "type": "string", "description": "When the broker last changed it." }, "overridden_by_user_id": { "type": "string", "description": "The broker who last changed it." } }, "required": [ "category", "subcategory", "excluded", "note", "overridden_at", "overridden_by_user_id" ], "additionalProperties": false } }, "required": [ "object", "id", "intake_id", "upload_id", "applicant_role", "date", "amount", "type", "description", "institution_name", "account_last4", "account_key", "category", "subcategory", "effective_category", "effective_subcategory", "excluded", "override" ], "additionalProperties": false }, "description": "The transactions that changed, as they now read." } }, "required": [ "updated", "skipped_transaction_ids", "transactions" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body changes nothing (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The intake does not exist, the broker cannot change it, or none of the ids is a transaction on it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/transactions/{transactionId}/override": { "delete": { "operationId": "clearIntakeTransactionOverride", "summary": "Undo the broker's change to a transaction", "description": "The transaction counts again as BrokerPlus read it, and the response is the transaction as it now reads. BrokerPlus then works the income out again. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_transaction", "description": "The type of this record. Always `intake_transaction`.", "type": "string", "enum": [ "intake_transaction" ] }, "id": { "type": "string", "description": "Stable identifier for the transaction, built from the statement, the day, the amount and the line. It contains `:`, so encode it in a path." }, "intake_id": { "type": "string", "description": "The intake." }, "upload_id": { "type": "string", "description": "The bank statement it is on. See `GET /v1/intakes/{id}/uploads/{uploadId}`." }, "applicant_role": { "type": "string", "enum": [ "primary", "co_applicant" ], "description": "Whose statement it is." }, "date": { "type": "string", "description": "The day of the transaction, as `YYYY-MM-DD`." }, "amount": { "type": "number", "description": "The amount, in dollars. Always positive: `type` says which way the money went." }, "type": { "type": "string", "enum": [ "credit", "debit" ], "description": "`credit` money in, `debit` money out." }, "description": { "type": "string", "description": "The line as the bank printed it." }, "institution_name": { "nullable": true, "description": "The bank. Null if the statement did not say.", "type": "string" }, "account_last4": { "nullable": true, "description": "The last 4 digits of the account number. The whole number is never on the API.", "type": "string" }, "account_key": { "type": "string", "description": "The account, as `excluded_account_keys` on the stated income scope names it." }, "category": { "nullable": true, "description": "What BrokerPlus read the transaction as. Null if it could not tell.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The finer kind BrokerPlus read. Null if it could not tell.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "effective_category": { "nullable": true, "description": "The category the income calculation uses: the broker's, if they changed it, or else `category`.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "effective_subcategory": { "nullable": true, "description": "The subcategory the income calculation uses: the broker's, if they changed it, or else `subcategory`.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out of the income calculation." }, "override": { "nullable": true, "description": "The broker's change to the transaction. Null if they never changed it.", "type": "object", "properties": { "category": { "nullable": true, "description": "The category the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "revenue", "expense", "transfer", "excluded" ] }, "subcategory": { "nullable": true, "description": "The subcategory the broker set. Null keeps what BrokerPlus read.", "type": "string", "enum": [ "advertising_marketing", "automotive", "insurance", "property_costs", "loan_payment", "revolving_credit", "bank_fees", "telecommunication_utilities", "interac_etransfer", "payroll", "gift", "nsf", "cash_deposit", "other" ] }, "excluded": { "type": "boolean", "description": "`true` if the broker took the transaction out." }, "note": { "nullable": true, "description": "The broker's note on why. Null if none.", "type": "string" }, "overridden_at": { "type": "string", "description": "When the broker last changed it." }, "overridden_by_user_id": { "type": "string", "description": "The broker who last changed it." } }, "required": [ "category", "subcategory", "excluded", "note", "overridden_at", "overridden_by_user_id" ], "additionalProperties": false } }, "required": [ "object", "id", "intake_id", "upload_id", "applicant_role", "date", "amount", "type", "description", "institution_name", "account_last4", "account_key", "category", "subcategory", "effective_category", "effective_subcategory", "excluded", "override" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/notes": { "get": { "operationId": "listIntakeNotes", "summary": "List the broker's notes on an intake", "description": "The notes brokers wrote on the items and files of a client's intake, newest first, replies included. Nobody outside the brokerage sees them.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "upload_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only notes on this file." }, { "name": "item_key", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only notes on this item, for any applicant." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_note", "description": "The type of this record. Always `intake_note`.", "type": "string", "enum": [ "intake_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "intake_id": { "type": "string", "description": "The intake the note is on." }, "upload_id": { "nullable": true, "description": "The file the note is on, from `GET /v1/intakes/{id}/uploads`. Null for a note on an item.", "type": "string" }, "item_key": { "nullable": true, "description": "The item the note is on, as `key` in `GET /v1/intakes/{id}/items`. Null for a note on a file.", "type": "string" }, "contact_id": { "nullable": true, "description": "The applicant whose item the note is on. Null for a note on a file.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "intake_id", "upload_id", "item_key", "contact_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createIntakeNote", "summary": "Write a note on an intake", "description": "Puts a note on one file (`upload_id`) or one item (`item_key`) of the intake, or replies to a note (`parent_id`). A teammate mentioned in the note is told, as in BrokerPlus. The client never sees it. A note cannot be changed or deleted afterwards, in BrokerPlus or here.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." }, "upload_id": { "description": "Put the note on this file, from `GET /v1/intakes/{id}/uploads`. Send this or `item_key`.", "type": "string", "minLength": 1 }, "item_key": { "description": "Put the note on this item, as `key` in `GET /v1/intakes/{id}/items`. Send this or `upload_id`.", "type": "string", "minLength": 1 }, "contact_id": { "description": "With `item_key`: the applicant whose item it is. Defaults to the primary client.", "type": "string", "minLength": 1 }, "parent_id": { "description": "Reply to this note. A reply goes on the same file or item as the note it answers, so send no `upload_id` or `item_key` with it. A reply cannot itself be replied to.", "type": "string", "minLength": 1 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_note", "description": "The type of this record. Always `intake_note`.", "type": "string", "enum": [ "intake_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "intake_id": { "type": "string", "description": "The intake the note is on." }, "upload_id": { "nullable": true, "description": "The file the note is on, from `GET /v1/intakes/{id}/uploads`. Null for a note on an item.", "type": "string" }, "item_key": { "nullable": true, "description": "The item the note is on, as `key` in `GET /v1/intakes/{id}/items`. Null for a note on a file.", "type": "string" }, "contact_id": { "nullable": true, "description": "The applicant whose item the note is on. Null for a note on a file.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "intake_id", "upload_id", "item_key", "contact_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Neither or both of `upload_id` and `item_key`, an anchor sent with `parent_id`, a reply to a reply, or a body with nothing visible in it (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The intake, the file or the note replied to does not exist, or the broker cannot change the intake (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The item is not on the intake for that applicant (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/notes/{noteId}": { "get": { "operationId": "getIntakeNote", "summary": "Retrieve a note on an intake", "description": "One note that a broker wrote on an item or file of a client's intake, or a reply to one. Nobody outside the brokerage sees it.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_note", "description": "The type of this record. Always `intake_note`.", "type": "string", "enum": [ "intake_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "intake_id": { "type": "string", "description": "The intake the note is on." }, "upload_id": { "nullable": true, "description": "The file the note is on, from `GET /v1/intakes/{id}/uploads`. Null for a note on an item.", "type": "string" }, "item_key": { "nullable": true, "description": "The item the note is on, as `key` in `GET /v1/intakes/{id}/items`. Null for a note on a file.", "type": "string" }, "contact_id": { "nullable": true, "description": "The applicant whose item the note is on. Null for a note on a file.", "type": "string" }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML, including teammate mentions. It is not Markdown." }, "author_id": { "type": "string", "description": "The broker who wrote it. Resolve against `GET /users/{id}`." }, "author_name": { "nullable": true, "description": "The author's name. Null if the broker has no name on file.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "intake_id", "upload_id", "item_key", "contact_id", "body", "author_id", "author_name", "parent_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/change-requests": { "get": { "operationId": "listIntakeChangeRequests", "summary": "List the changes asked of a client", "description": "Every answer and file the broker asked the client to fix on this intake, newest first. To ask for a new one, use `POST /intakes/{id}/request-changes`.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "resolved" ] }, "description": "`open` or `resolved`. Any other value gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "intake_change_request", "description": "The type of this record. Always `intake_change_request`.", "type": "string", "enum": [ "intake_change_request" ] }, "id": { "type": "string", "description": "Stable identifier for the change request." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "target": { "type": "string", "enum": [ "answer", "upload" ], "description": "What the client is asked to fix: `answer` an answer they gave, `upload` a file they sent." }, "question_key": { "nullable": true, "description": "The `key` of the answer to fix, from `GET /v1/intakes/{id}/answers`. Null for an `upload`.", "type": "string" }, "upload_id": { "nullable": true, "description": "The file to replace, from `GET /v1/intakes/{id}/uploads`. Null for an `answer`, or once the file is gone.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant asked to fix it." }, "comment": { "type": "string", "description": "What the broker told the client about it." }, "status": { "type": "string", "enum": [ "open", "resolved" ], "description": "`open` until the client fixes it or the broker resolves it, then `resolved`." }, "broker_user_id": { "type": "string", "description": "The broker who asked for it." }, "created_at": { "type": "string", "description": "When it was asked for (ISO 8601)." }, "resolved_at": { "nullable": true, "description": "When it was resolved (ISO 8601). Null while open.", "type": "string" } }, "required": [ "object", "id", "intake_id", "target", "question_key", "upload_id", "contact_id", "comment", "status", "broker_user_id", "created_at", "resolved_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/change-requests/{crId}": { "patch": { "operationId": "updateIntakeChangeRequest", "summary": "Reword a change asked of a client", "description": "Changes what the broker told the client about it. Nothing is sent: the client sees the new words the next time they open their link.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "crId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The new words for the client. The client sees them the next time they open their link." } }, "required": [ "comment" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_change_request", "description": "The type of this record. Always `intake_change_request`.", "type": "string", "enum": [ "intake_change_request" ] }, "id": { "type": "string", "description": "Stable identifier for the change request." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "target": { "type": "string", "enum": [ "answer", "upload" ], "description": "What the client is asked to fix: `answer` an answer they gave, `upload` a file they sent." }, "question_key": { "nullable": true, "description": "The `key` of the answer to fix, from `GET /v1/intakes/{id}/answers`. Null for an `upload`.", "type": "string" }, "upload_id": { "nullable": true, "description": "The file to replace, from `GET /v1/intakes/{id}/uploads`. Null for an `answer`, or once the file is gone.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant asked to fix it." }, "comment": { "type": "string", "description": "What the broker told the client about it." }, "status": { "type": "string", "enum": [ "open", "resolved" ], "description": "`open` until the client fixes it or the broker resolves it, then `resolved`." }, "broker_user_id": { "type": "string", "description": "The broker who asked for it." }, "created_at": { "type": "string", "description": "When it was asked for (ISO 8601)." }, "resolved_at": { "nullable": true, "description": "When it was resolved (ISO 8601). Null while open.", "type": "string" } }, "required": [ "object", "id", "intake_id", "target", "question_key", "upload_id", "contact_id", "comment", "status", "broker_user_id", "created_at", "resolved_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteIntakeChangeRequest", "summary": "Withdraw a change asked of a client", "description": "Removes it, as the broker does in the request panel. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "crId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/change-requests/{crId}/resolve": { "post": { "operationId": "resolveIntakeChangeRequest", "summary": "Mark a change as done", "description": "Marks it `resolved`, as the broker does in the request panel. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "crId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_change_request", "description": "The type of this record. Always `intake_change_request`.", "type": "string", "enum": [ "intake_change_request" ] }, "id": { "type": "string", "description": "Stable identifier for the change request." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "target": { "type": "string", "enum": [ "answer", "upload" ], "description": "What the client is asked to fix: `answer` an answer they gave, `upload` a file they sent." }, "question_key": { "nullable": true, "description": "The `key` of the answer to fix, from `GET /v1/intakes/{id}/answers`. Null for an `upload`.", "type": "string" }, "upload_id": { "nullable": true, "description": "The file to replace, from `GET /v1/intakes/{id}/uploads`. Null for an `answer`, or once the file is gone.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant asked to fix it." }, "comment": { "type": "string", "description": "What the broker told the client about it." }, "status": { "type": "string", "enum": [ "open", "resolved" ], "description": "`open` until the client fixes it or the broker resolves it, then `resolved`." }, "broker_user_id": { "type": "string", "description": "The broker who asked for it." }, "created_at": { "type": "string", "description": "When it was asked for (ISO 8601)." }, "resolved_at": { "nullable": true, "description": "When it was resolved (ISO 8601). Null while open.", "type": "string" } }, "required": [ "object", "id", "intake_id", "target", "question_key", "upload_id", "contact_id", "comment", "status", "broker_user_id", "created_at", "resolved_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/change-requests/{crId}/reopen": { "post": { "operationId": "reopenIntakeChangeRequest", "summary": "Reopen a change", "description": "Puts a resolved change back to `open`. Nothing goes to the client.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "crId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "intake_change_request", "description": "The type of this record. Always `intake_change_request`.", "type": "string", "enum": [ "intake_change_request" ] }, "id": { "type": "string", "description": "Stable identifier for the change request." }, "intake_id": { "type": "string", "description": "The intake it is on." }, "target": { "type": "string", "enum": [ "answer", "upload" ], "description": "What the client is asked to fix: `answer` an answer they gave, `upload` a file they sent." }, "question_key": { "nullable": true, "description": "The `key` of the answer to fix, from `GET /v1/intakes/{id}/answers`. Null for an `upload`.", "type": "string" }, "upload_id": { "nullable": true, "description": "The file to replace, from `GET /v1/intakes/{id}/uploads`. Null for an `answer`, or once the file is gone.", "type": "string" }, "contact_id": { "type": "string", "description": "The applicant asked to fix it." }, "comment": { "type": "string", "description": "What the broker told the client about it." }, "status": { "type": "string", "enum": [ "open", "resolved" ], "description": "`open` until the client fixes it or the broker resolves it, then `resolved`." }, "broker_user_id": { "type": "string", "description": "The broker who asked for it." }, "created_at": { "type": "string", "description": "When it was asked for (ISO 8601)." }, "resolved_at": { "nullable": true, "description": "When it was resolved (ISO 8601). Null while open.", "type": "string" } }, "required": [ "object", "id", "intake_id", "target", "question_key", "upload_id", "contact_id", "comment", "status", "broker_user_id", "created_at", "resolved_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/intakes/{id}/link": { "post": { "operationId": "createIntakeLinkForClient", "summary": "Issue a client's intake link", "description": "Issues a link for one client on this intake. BrokerPlus keeps only a fingerprint of a link, so a link already sent cannot be read back: this issues another one, and every link issued for the same intake keeps working until it expires. Pass `contact_id` for a co-applicant.", "tags": [ "Intakes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The co-applicant to issue it for. Omit it for the client the intake is in the name of." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "The link for this client. Send it to them; anybody holding it is them." }, "expires_at": { "type": "string", "description": "When it stops working. Opening it moves this later." } }, "required": [ "url", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "description": "The action queue, newest first. Filter by `status` to fetch only what is still open.", "tags": [ "Tasks" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ] }, "description": "Filter by task status." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only tasks on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only tasks for this contact." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createTask", "summary": "Create a task", "description": "File a manual task for the broker's queue. The task takes the team of its deal or contact, or the broker's own team. Set `assignee_user_id` to assign it on creation, or leave it blank to file it unassigned. Supports `Idempotency-Key`.", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short summary shown to the broker." }, "body": { "description": "Longer detail.", "nullable": true, "type": "string", "maxLength": 10000 }, "deal_id": { "description": "Attach the task to this deal. The task takes the deal's team.", "nullable": true, "type": "string" }, "contact_id": { "description": "Attach the task to this contact. With a deal, the contact must be on the same team.", "nullable": true, "type": "string" }, "assignee_user_id": { "description": "The broker who owns the task. Must be an active user of the brokerage who is eligible for the task's team and deal. Null leaves the task unassigned. An ineligible assignee fails with INVALID_ASSIGNEE.", "nullable": true, "type": "string" }, "due_date": { "description": "ISO 8601 timestamp. When the task is due.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "priority": { "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). Defaults to 0.5.", "type": "number", "minimum": 0, "maximum": 1 }, "category": { "description": "Override the category derived from the task type. Mutually exclusive with custom_category_id.", "type": "string" }, "custom_category_id": { "description": "Attach to a custom category created by the brokerage. Mutually exclusive with category.", "type": "string" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The deal or contact is not found or not writable (INVALID_DEAL, INVALID_CONTACT), or the assignee is not eligible for the task's team and deal (INVALID_ASSIGNEE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker belongs to no team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}": { "get": { "operationId": "getTask", "summary": "Retrieve a task", "description": "A single task by id.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Edit a task's fields or reassign it. Reassignment checks the new assignee's eligibility for the task's team and deal, the same as the dashboard. Sending the current assignee again is not a reassignment.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "New summary.", "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "description": "New detail, or null to clear it.", "nullable": true, "type": "string", "maxLength": 10000 }, "due_date": { "description": "ISO 8601. New due date, or null to clear it.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "pinned": { "description": "Pin the task to the top of the broker's queue.", "type": "boolean" }, "progress": { "description": "How far along it is, a whole percent from 0 to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "snoozed_until": { "description": "ISO 8601. Put the task aside until this time, or null to bring it back now.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "assignee_user_id": { "description": "The broker who owns the task. Must be an active user of the brokerage who is eligible for the task's team and deal. Null leaves the task unassigned. An ineligible assignee fails with INVALID_ASSIGNEE.", "nullable": true, "type": "string" }, "category": { "description": "Override the task type's category, or null to use the type's default. Mutually exclusive with custom_category_id.", "nullable": true, "type": "string" }, "custom_category_id": { "description": "Assign to a custom category, or null to clear and use the type's default. Mutually exclusive with category.", "nullable": true, "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The assignee is not eligible for the task's team and deal (INVALID_ASSIGNEE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/work-watches": { "get": { "operationId": "listWorkWatches", "summary": "List who deals are waiting on", "description": "What each deal is waiting for and who owes the next move, as the waiting-on chips on a deal card show it. BrokerPlus starts, escalates, and ends each watch from what happens on the deal, so this is read-only. Without `status`, every watch is listed, oldest wait first; send `status=active` for what is still waiting.", "tags": [ "Tasks" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the watches on this deal." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "resolved", "cancelled" ] }, "description": "Only watches in this state." }, { "name": "waiting_on", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "borrower", "lender", "broker", "system", "third_party" ] }, "description": "Only watches waiting on this party." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "work_watch", "description": "The type of this record. Always `work_watch`.", "type": "string", "enum": [ "work_watch" ] }, "id": { "type": "string", "description": "Stable identifier for the watch." }, "deal_id": { "nullable": true, "description": "The deal that is waiting. Null for a watch on something outside a deal.", "type": "string" }, "kind": { "type": "string", "description": "What the deal is waiting for, for example `waiting_on_borrower` (documents or answers the client owes) or `waiting_on_lender` (a lender's reply). New kinds can appear, so treat an unknown value as text." }, "status": { "type": "string", "enum": [ "active", "resolved", "cancelled" ], "description": "`active`: the deal is still waiting. `resolved`: the thing it waited for arrived. `cancelled`: BrokerPlus stopped waiting before the answer arrived." }, "waiting_on": { "type": "string", "enum": [ "borrower", "lender", "broker", "system", "third_party" ], "description": "Who owes the next move: `borrower`, `lender`, `broker`, `system` (BrokerPlus itself), or `third_party` (for example a lawyer or an appraiser)." }, "waiting_on_contact_id": { "nullable": true, "description": "The contact who owes the next move, when it is one person in the book. Null otherwise.", "type": "string" }, "waiting_on_user_id": { "nullable": true, "description": "The broker who owes the next move, when it is a person on the team. Null otherwise.", "type": "string" }, "since_at": { "type": "string", "description": "When the wait started." }, "due_at": { "nullable": true, "description": "When the answer is due. Null if there is no due date.", "type": "string" }, "escalation_level": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How overdue the wait is. `0` is on time; each higher number is a later reminder step. The deal card colours the wait by this number." }, "last_escalated_at": { "nullable": true, "description": "When the wait last moved up a level. Null if it never did.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When the wait ended. Null while it is `active`.", "type": "string" }, "resolved_reason": { "nullable": true, "description": "Why the wait ended, in BrokerPlus's words. Null while it is `active`.", "type": "string" }, "task_id": { "nullable": true, "description": "The task BrokerPlus made to chase the wait, if it made one. Read it with `GET /v1/tasks/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus started watching." }, "updated_at": { "type": "string", "description": "When the watch last changed." } }, "required": [ "object", "id", "deal_id", "kind", "status", "waiting_on", "waiting_on_contact_id", "waiting_on_user_id", "since_at", "due_at", "escalation_level", "last_escalated_at", "resolved_at", "resolved_reason", "task_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/work-watches/{id}": { "get": { "operationId": "getWorkWatch", "summary": "Retrieve a watch", "description": "One watch: what a deal is waiting for, who owes it, and since when.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "work_watch", "description": "The type of this record. Always `work_watch`.", "type": "string", "enum": [ "work_watch" ] }, "id": { "type": "string", "description": "Stable identifier for the watch." }, "deal_id": { "nullable": true, "description": "The deal that is waiting. Null for a watch on something outside a deal.", "type": "string" }, "kind": { "type": "string", "description": "What the deal is waiting for, for example `waiting_on_borrower` (documents or answers the client owes) or `waiting_on_lender` (a lender's reply). New kinds can appear, so treat an unknown value as text." }, "status": { "type": "string", "enum": [ "active", "resolved", "cancelled" ], "description": "`active`: the deal is still waiting. `resolved`: the thing it waited for arrived. `cancelled`: BrokerPlus stopped waiting before the answer arrived." }, "waiting_on": { "type": "string", "enum": [ "borrower", "lender", "broker", "system", "third_party" ], "description": "Who owes the next move: `borrower`, `lender`, `broker`, `system` (BrokerPlus itself), or `third_party` (for example a lawyer or an appraiser)." }, "waiting_on_contact_id": { "nullable": true, "description": "The contact who owes the next move, when it is one person in the book. Null otherwise.", "type": "string" }, "waiting_on_user_id": { "nullable": true, "description": "The broker who owes the next move, when it is a person on the team. Null otherwise.", "type": "string" }, "since_at": { "type": "string", "description": "When the wait started." }, "due_at": { "nullable": true, "description": "When the answer is due. Null if there is no due date.", "type": "string" }, "escalation_level": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How overdue the wait is. `0` is on time; each higher number is a later reminder step. The deal card colours the wait by this number." }, "last_escalated_at": { "nullable": true, "description": "When the wait last moved up a level. Null if it never did.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When the wait ended. Null while it is `active`.", "type": "string" }, "resolved_reason": { "nullable": true, "description": "Why the wait ended, in BrokerPlus's words. Null while it is `active`.", "type": "string" }, "task_id": { "nullable": true, "description": "The task BrokerPlus made to chase the wait, if it made one. Read it with `GET /v1/tasks/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus started watching." }, "updated_at": { "type": "string", "description": "When the watch last changed." } }, "required": [ "object", "id", "deal_id", "kind", "status", "waiting_on", "waiting_on_contact_id", "waiting_on_user_id", "since_at", "due_at", "escalation_level", "last_escalated_at", "resolved_at", "resolved_reason", "task_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}/complete": { "post": { "operationId": "completeTask", "summary": "Complete a task", "description": "Marks the task done. Send `resolution` to record why. The body is optional.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolution": { "description": "Optional. Why the task is done, e.g. `Client sent the paystub`. Text past 2,000 characters is cut.", "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}/cancel": { "post": { "operationId": "cancelTask", "summary": "Cancel a task", "description": "Takes the task out of the queue without completing it. Undo it with `POST /tasks/{id}/reopen`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The task is already cancelled (ALREADY_CANCELLED), or it is an approval only the broker can decide (APPROVAL_TASK).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}/reopen": { "post": { "operationId": "reopenTask", "summary": "Reopen a task", "description": "Puts a completed or cancelled task back in the queue as `pending`. Its completion is cleared.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task", "description": "The type of this record. Always `task`.", "type": "string", "enum": [ "task" ] }, "id": { "type": "string", "description": "Stable identifier for the task." }, "deal_id": { "nullable": true, "description": "The deal this task belongs to. Null if it has no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The name of that deal. Null if the task has no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact this task belongs to. Null if it has no contact.", "type": "string" }, "contact_name": { "nullable": true, "description": "The name of that contact. Null if the task has no contact.", "type": "string" }, "type": { "type": "string", "description": "What kind of action this is. New types are added as the product grows." }, "category": { "nullable": true, "description": "The task's category. Built-in category, derived from type if null, or a custom category name.", "type": "string" }, "custom_category": { "nullable": true, "description": "The custom category if the task carries one. Null if using a built-in category.", "type": "object", "properties": { "id": { "type": "string", "description": "The custom category's id." }, "name": { "type": "string", "description": "The custom category's name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "title": { "type": "string", "description": "Short summary shown to the broker." }, "body": { "nullable": true, "description": "Longer detail, when the task carries any.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "system_resolved", "cancelled" ], "description": "`system_resolved` means BrokerPlus satisfied it without the broker acting." }, "due_date": { "nullable": true, "description": "When the task is due, if it has a deadline.", "type": "string" }, "completed_at": { "nullable": true, "description": "When it was completed. Null while still open.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The broker who owns the task. Null if unassigned.", "type": "string" }, "assignee_name": { "nullable": true, "description": "The assigned broker's name. Null if unassigned or the broker has no name on file.", "type": "string" }, "priority": { "type": "number", "description": "Rank in the broker's queue from 0 (lowest) to 1 (highest). The value sent on create, 0.5 by default." }, "pinned": { "type": "boolean", "description": "True when the task is pinned to the top of the broker's queue." }, "resolution": { "nullable": true, "description": "The note sent with `POST /v1/tasks/{id}/complete`. Null when none was sent.", "type": "string" }, "parent_task_id": { "nullable": true, "description": "The task this one is a step of. Null for a task that stands on its own.", "type": "string" }, "provenance": { "type": "string", "enum": [ "user", "deterministic_rule", "agent_inference", "automation" ], "description": "Who filed it: `user` (a person, or this API), `deterministic_rule` (a BrokerPlus rule, e.g. a closing date coming up), `agent_inference` (the BrokerPlus assistant), or `automation` (one of the brokerage's automations)." }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How far along the broker says the task is, as a whole percent from 0 to 100." }, "snoozed_until": { "nullable": true, "description": "The broker has put the task aside until this time. Null when it is not snoozed.", "type": "string" }, "completed_by_user_id": { "nullable": true, "description": "The broker who completed it. Null while open, or when BrokerPlus resolved it.", "type": "string" }, "created_at": { "type": "string", "description": "When the task was filed." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "deal_id", "deal_name", "contact_id", "contact_name", "type", "category", "custom_category", "title", "body", "status", "due_date", "completed_at", "assignee_user_id", "assignee_name", "priority", "pinned", "resolution", "parent_task_id", "provenance", "progress", "snoozed_until", "completed_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The task is already open (ALREADY_OPEN), or it is an approval only the broker can decide (APPROVAL_TASK).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/bulk": { "post": { "operationId": "bulkTasks", "summary": "Complete, cancel or reopen many tasks", "description": "Applies one action to up to 200 tasks at once, as a select-all in the broker's queue does. A task that is already in that state is skipped rather than failing the request, and so is an approval, which only the broker can decide. The response lists what changed and what was skipped.", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "complete", "cancel", "reopen" ], "description": "What to do to every task in the list: `complete`, `cancel`, or `reopen`." }, "task_ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The tasks to change, up to 200." } }, "required": [ "action", "task_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "complete", "cancel", "reopen" ], "description": "The action you sent." }, "updated_ids": { "type": "array", "items": { "type": "string" }, "description": "The tasks that changed." }, "skipped_ids": { "type": "array", "items": { "type": "string" }, "description": "The tasks you sent that did not change: a task already in that state, an approval only the broker can decide, or an id you cannot reach." } }, "required": [ "action", "updated_ids", "skipped_ids" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}/notes": { "get": { "operationId": "listTaskNotes", "summary": "List a task's notes", "description": "Pinned notes first, then the newest. Task notes are internal to the brokerage. A client never sees them.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "task_note", "description": "The type of this record. Always `task_note`.", "type": "string", "enum": [ "task_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "nullable": true, "description": "The broker who wrote it. Null when the BrokerPlus assistant wrote it.", "type": "string" }, "author_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant wrote the note." } }, "required": [ "object", "id", "body", "pinned", "author_id", "author_name", "parent_id", "created_at", "updated_at", "created_by_agent" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createTaskNote", "summary": "Add a note to a task", "description": "A teammate named with a mention gets a notification, as in BrokerPlus. Supports `Idempotency-Key`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content." }, "pinned": { "description": "Defaults to `false`.", "type": "boolean" }, "parent_id": { "description": "Reply to this note. Must belong to the same record, and cannot itself be a reply.", "nullable": true, "type": "string" } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task_note", "description": "The type of this record. Always `task_note`.", "type": "string", "enum": [ "task_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "nullable": true, "description": "The broker who wrote it. Null when the BrokerPlus assistant wrote it.", "type": "string" }, "author_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant wrote the note." } }, "required": [ "object", "id", "body", "pinned", "author_id", "author_name", "parent_id", "created_at", "updated_at", "created_by_agent" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tasks/{id}/notes/{noteId}": { "patch": { "operationId": "updateTaskNote", "summary": "Update a note on a task", "description": "Edit the words, pin or unpin the note. Only the fields you send change. A teammate newly named with a mention gets a notification, as in BrokerPlus.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "description": "The new note body. Plain text or HTML. Unsafe HTML is removed. The result must contain visible content.", "type": "string", "minLength": 1, "maxLength": 20000 }, "pinned": { "description": "`true` pins the note to the top of the record. A pin does not change `updated_at`.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task_note", "description": "The type of this record. Always `task_note`.", "type": "string", "enum": [ "task_note" ] }, "id": { "type": "string", "description": "Stable identifier for the note." }, "body": { "type": "string", "description": "The note body. It can contain sanitized HTML. It is not Markdown. A teammate mention is `@Name`." }, "pinned": { "type": "boolean", "description": "Pinned notes surface at the top of the record in BrokerPlus." }, "author_id": { "nullable": true, "description": "The broker who wrote it. Null when the BrokerPlus assistant wrote it.", "type": "string" }, "author_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "parent_id": { "nullable": true, "description": "Set when this note is a reply. Replies are one level deep only.", "type": "string" }, "created_at": { "type": "string", "description": "When the note was written." }, "updated_at": { "type": "string", "description": "Last edit." }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant wrote the note." } }, "required": [ "object", "id", "body", "pinned", "author_id", "author_name", "parent_id", "created_at", "updated_at", "created_by_agent" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteTaskNote", "summary": "Delete a note from a task", "description": "Deletes the note. You cannot undo this. Only the broker who wrote the note can delete it, and a note that the BrokerPlus assistant wrote cannot be deleted (403 NOT_AUTHOR).", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/note-types": { "get": { "operationId": "listNoteTypes", "summary": "List note types", "description": "The kinds that the broker's team files deal notes and contact notes under: the kinds that come with BrokerPlus, as the team changed them, then the kinds the team added. A kind the team removed is not listed. Send a `slug` as `type` on a note.", "tags": [ "Notes" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "deal", "contact" ] }, "description": "`deal` or `contact`. Without it, you get both lists, deal first." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "note_type", "description": "The type of this record. Always `note_type`.", "type": "string", "enum": [ "note_type" ] }, "scope": { "type": "string", "enum": [ "deal", "contact" ], "description": "`deal` for the kinds of deal notes, `contact` for the kinds of contact notes. The two lists are separate." }, "slug": { "type": "string", "description": "The stable name of the kind. A note stores it in `type`. It never changes, even when the broker renames the kind." }, "name": { "type": "string", "description": "The name the broker sees on the note." }, "color": { "type": "string", "description": "The colour of the chip: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex." }, "template": { "nullable": true, "description": "The sanitized HTML that a new note of this kind starts with in BrokerPlus. Null when the kind has no template.", "type": "string" }, "built_in": { "type": "boolean", "description": "True when the kind comes with BrokerPlus. The team can rename or remove a builtin kind, but `general` always stays." } }, "required": [ "object", "scope", "slug", "name", "color", "template", "built_in" ], "additionalProperties": false }, "description": "Every kind a note can have, in the order BrokerPlus shows them." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createNoteType", "summary": "Create a note type", "description": "Adds a kind to the deal or contact list of the broker's team. BrokerPlus makes the `slug` from the `name`. If the team removed a kind with the same `slug`, this brings that kind back, and the notes filed under it show its name again.", "tags": [ "Notes" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "deal", "contact" ], "description": "`deal` or `contact`: the list that gets the new kind." }, "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The name of the kind. 1 to 40 characters." }, "color": { "type": "string", "description": "The colour of the chip: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`." }, "template": { "type": "string", "maxLength": 20000, "description": "Plain text or HTML that a new note of this kind starts with. Unsafe HTML is removed. Send `\"\"` for none." } }, "required": [ "scope", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_type", "description": "The type of this record. Always `note_type`.", "type": "string", "enum": [ "note_type" ] }, "scope": { "type": "string", "enum": [ "deal", "contact" ], "description": "`deal` for the kinds of deal notes, `contact` for the kinds of contact notes. The two lists are separate." }, "slug": { "type": "string", "description": "The stable name of the kind. A note stores it in `type`. It never changes, even when the broker renames the kind." }, "name": { "type": "string", "description": "The name the broker sees on the note." }, "color": { "type": "string", "description": "The colour of the chip: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex." }, "template": { "nullable": true, "description": "The sanitized HTML that a new note of this kind starts with in BrokerPlus. Null when the kind has no template.", "type": "string" }, "built_in": { "type": "boolean", "description": "True when the kind comes with BrokerPlus. The team can rename or remove a builtin kind, but `general` always stays." } }, "required": [ "object", "scope", "slug", "name", "color", "template", "built_in" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The name has no letters or numbers (VALIDATION_ERROR), or the broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The list has a kind with this `slug` (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/note-types/{scope}/{slug}": { "patch": { "operationId": "updateNoteType", "summary": "Update a note type", "description": "Changes the name, colour, or template of a kind. The `slug` does not change, so every note filed under the kind keeps it. Changing a kind that comes with BrokerPlus changes it for the broker's team only. Changing a builtin kind that the team removed brings it back.", "tags": [ "Notes" ], "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The name of the kind. 1 to 40 characters." }, "color": { "type": "string", "description": "The colour of the chip: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex. Defaults to `navy`." }, "template": { "nullable": true, "type": "string", "maxLength": 20000, "description": "Plain text or HTML that a new note of this kind starts with. Unsafe HTML is removed. Send `\"\"` for none." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "note_type", "description": "The type of this record. Always `note_type`.", "type": "string", "enum": [ "note_type" ] }, "scope": { "type": "string", "enum": [ "deal", "contact" ], "description": "`deal` for the kinds of deal notes, `contact` for the kinds of contact notes. The two lists are separate." }, "slug": { "type": "string", "description": "The stable name of the kind. A note stores it in `type`. It never changes, even when the broker renames the kind." }, "name": { "type": "string", "description": "The name the broker sees on the note." }, "color": { "type": "string", "description": "The colour of the chip: `navy`, `amber`, `slate`, `red`, or a `#rrggbb` hex." }, "template": { "nullable": true, "description": "The sanitized HTML that a new note of this kind starts with in BrokerPlus. Null when the kind has no template.", "type": "string" }, "built_in": { "type": "boolean", "description": "True when the kind comes with BrokerPlus. The team can rename or remove a builtin kind, but `general` always stays." } }, "required": [ "object", "scope", "slug", "name", "color", "template", "built_in" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The list has no kind with this `slug` that the broker can change (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteNoteType", "summary": "Remove a note type", "description": "Removes a kind from the list. The notes filed under it keep their `type`, and BrokerPlus shows them as an unknown kind. To bring the kind back, create a kind with the same name. The response `id` is the `slug`.", "tags": [ "Notes" ], "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The kind is `general`, which cannot be removed (NOT_REMOVABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The list has no kind with this `slug` that the broker can change (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/task-categories": { "get": { "operationId": "listTaskCategories", "summary": "List task categories", "description": "The built-in task categories, then the custom categories of the key's team in the team's order. A built-in category that the team hides has `hidden: true`.", "tags": [ "Tasks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "task_category", "description": "The type of this record. Always `task_category`.", "type": "string", "enum": [ "task_category" ] }, "key": { "type": "string", "description": "Unique identifier. Built-in categories use the category name; custom use `custom:`." }, "name": { "type": "string", "description": "Display name shown to the broker." }, "built_in": { "type": "boolean", "description": "True for system-provided categories; false for custom ones created by the brokerage." }, "team_id": { "description": "For custom categories only: the team that created it. Null for built-ins.", "type": "string" }, "id": { "description": "For custom categories only: the id in `key` after `custom:`. Send it as `custom_category_id` on a task.", "type": "string" }, "position": { "description": "For custom categories only: the team's own order, lowest first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hidden": { "type": "boolean", "description": "True for a built-in category that the team took out of its pickers. A task can still have it, and filters still show it. Always false on a custom category." }, "created_at": { "description": "For custom categories only: when the team added it.", "type": "string" }, "updated_at": { "description": "For custom categories only: the last rename or reorder.", "type": "string" } }, "required": [ "object", "key", "name", "built_in", "hidden" ], "additionalProperties": false }, "description": "Every category available on a task, built-in and custom." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createTaskCategory", "summary": "Create a task category", "description": "Adds a custom category to the key's team, after its other categories. Only the team's broker or a brokerage admin can change the team's categories. A team can have 25 custom categories.", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The category's name. It must be different from the team's other categories, in any letter case." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task_category", "description": "The type of this record. Always `task_category`.", "type": "string", "enum": [ "task_category" ] }, "key": { "type": "string", "description": "Unique identifier. Built-in categories use the category name; custom use `custom:`." }, "name": { "type": "string", "description": "Display name shown to the broker." }, "built_in": { "type": "boolean", "description": "True for system-provided categories; false for custom ones created by the brokerage." }, "team_id": { "description": "For custom categories only: the team that created it. Null for built-ins.", "type": "string" }, "id": { "description": "For custom categories only: the id in `key` after `custom:`. Send it as `custom_category_id` on a task.", "type": "string" }, "position": { "description": "For custom categories only: the team's own order, lowest first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hidden": { "type": "boolean", "description": "True for a built-in category that the team took out of its pickers. A task can still have it, and filters still show it. Always false on a custom category." }, "created_at": { "description": "For custom categories only: when the team added it.", "type": "string" }, "updated_at": { "description": "For custom categories only: the last rename or reorder.", "type": "string" } }, "required": [ "object", "key", "name", "built_in", "hidden" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not the team's broker or a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team has a category with this name (DUPLICATE), has 25 categories (LIMIT_REACHED), or the broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/task-categories/hidden": { "post": { "operationId": "setHiddenTaskCategories", "summary": "Hide built-in task categories", "description": "Sets which built-in categories the team takes out of its pickers. A hidden category still collects the tasks that BrokerPlus makes, and filters still show it. Only the team's broker or a brokerage admin can do this. Returns every category.", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hidden": { "maxItems": 8, "type": "array", "items": { "type": "string" }, "description": "The `key` of every built-in category to take out of the team's pickers. It replaces the list. Send an empty list to show them all. You cannot hide `admin`, because a new task starts in it." } }, "required": [ "hidden" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "task_category", "description": "The type of this record. Always `task_category`.", "type": "string", "enum": [ "task_category" ] }, "key": { "type": "string", "description": "Unique identifier. Built-in categories use the category name; custom use `custom:`." }, "name": { "type": "string", "description": "Display name shown to the broker." }, "built_in": { "type": "boolean", "description": "True for system-provided categories; false for custom ones created by the brokerage." }, "team_id": { "description": "For custom categories only: the team that created it. Null for built-ins.", "type": "string" }, "id": { "description": "For custom categories only: the id in `key` after `custom:`. Send it as `custom_category_id` on a task.", "type": "string" }, "position": { "description": "For custom categories only: the team's own order, lowest first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hidden": { "type": "boolean", "description": "True for a built-in category that the team took out of its pickers. A task can still have it, and filters still show it. Always false on a custom category." }, "created_at": { "description": "For custom categories only: when the team added it.", "type": "string" }, "updated_at": { "description": "For custom categories only: the last rename or reorder.", "type": "string" } }, "required": [ "object", "key", "name", "built_in", "hidden" ], "additionalProperties": false }, "description": "Every category available on a task, built-in and custom." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not the team's broker or a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker is not on a team (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/task-categories/{id}": { "patch": { "operationId": "renameTaskCategory", "summary": "Rename a task category", "description": "Renames a custom category of the key's team. The tasks in the category keep it. Only the team's broker or a brokerage admin can do this.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The category's name. It must be different from the team's other categories, in any letter case." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "task_category", "description": "The type of this record. Always `task_category`.", "type": "string", "enum": [ "task_category" ] }, "key": { "type": "string", "description": "Unique identifier. Built-in categories use the category name; custom use `custom:`." }, "name": { "type": "string", "description": "Display name shown to the broker." }, "built_in": { "type": "boolean", "description": "True for system-provided categories; false for custom ones created by the brokerage." }, "team_id": { "description": "For custom categories only: the team that created it. Null for built-ins.", "type": "string" }, "id": { "description": "For custom categories only: the id in `key` after `custom:`. Send it as `custom_category_id` on a task.", "type": "string" }, "position": { "description": "For custom categories only: the team's own order, lowest first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hidden": { "type": "boolean", "description": "True for a built-in category that the team took out of its pickers. A task can still have it, and filters still show it. Always false on a custom category." }, "created_at": { "description": "For custom categories only: when the team added it.", "type": "string" }, "updated_at": { "description": "For custom categories only: the last rename or reorder.", "type": "string" } }, "required": [ "object", "key", "name", "built_in", "hidden" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not the team's broker or a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The category is not a custom category of the key's team (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The team has another category with this name (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteTaskCategory", "summary": "Delete a task category", "description": "Deletes a custom category of the key's team, the same as in BrokerPlus. The tasks in it go back to their built-in category. Only the team's broker or a brokerage admin can do this.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not the team's broker or a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The category is not a custom category of the key's team (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "description": "Every endpoint that the broker of this key registered. Signing secrets are never included.", "tags": [ "Webhooks" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "webhook", "description": "The type of this record. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Stable identifier for the endpoint." }, "url": { "type": "string", "description": "Where deliveries are POSTed." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ] }, "description": "Which events this endpoint receives." }, "enabled": { "type": "boolean", "description": "Set to false automatically after 20 events in a row fail every attempt. Re-enable with PATCH once the endpoint is fixed." }, "last_success_at": { "nullable": true, "description": "Last delivery your endpoint accepted with a 2xx.", "type": "string" }, "last_failure_at": { "nullable": true, "description": "Last delivery that failed. Check this first when events go quiet.", "type": "string" }, "failure_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Events in a row that failed every attempt. Back to 0 after a delivery succeeds or you re-enable the endpoint. At 20 the endpoint turns itself off." }, "created_at": { "type": "string", "description": "When the endpoint was registered." }, "updated_at": { "type": "string", "description": "Last change to the endpoint, including a change BrokerPlus made, such as turning it off." } }, "required": [ "object", "id", "url", "events", "enabled", "last_success_at", "last_failure_at", "failure_count", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint", "description": "The response carries the signing secret. It is shown once and never returned again.", "tags": [ "Webhooks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Must be https and publicly resolvable. Private and loopback addresses are refused." }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ] }, "description": "At least one event. Unknown names are refused." } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "webhook", "description": "The type of this record. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Stable identifier for the endpoint." }, "url": { "type": "string", "description": "Where deliveries are POSTed." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ] }, "description": "Which events this endpoint receives." }, "enabled": { "type": "boolean", "description": "Set to false automatically after 20 events in a row fail every attempt. Re-enable with PATCH once the endpoint is fixed." }, "last_success_at": { "nullable": true, "description": "Last delivery your endpoint accepted with a 2xx.", "type": "string" }, "last_failure_at": { "nullable": true, "description": "Last delivery that failed. Check this first when events go quiet.", "type": "string" }, "failure_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Events in a row that failed every attempt. Back to 0 after a delivery succeeds or you re-enable the endpoint. At 20 the endpoint turns itself off." }, "created_at": { "type": "string", "description": "When the endpoint was registered." }, "updated_at": { "type": "string", "description": "Last change to the endpoint, including a change BrokerPlus made, such as turning it off." }, "secret": { "type": "string", "description": "Shown once. Store it - it is never returned again." } }, "required": [ "object", "id", "url", "events", "enabled", "last_success_at", "last_failure_at", "failure_count", "created_at", "updated_at", "secret" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "`WEBHOOK_EXISTS`: you already registered this URL for the same events. `details.webhook_id` names that endpoint; change its events with `PATCH` instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "summary": "Update a webhook endpoint", "description": "Change the URL, the subscribed events, or re-enable an endpoint we disabled. Re-enabling also clears the failure count.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Move deliveries to this URL. Same rules as on create.", "type": "string", "maxLength": 2000, "format": "uri" }, "events": { "description": "Replace the subscribed event set.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ] } }, "enabled": { "description": "Re-enable an endpoint we disabled after repeated failures, or pause one yourself. Events that happen while an endpoint is off are not sent later; read them back with `updated_since`.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "webhook", "description": "The type of this record. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Stable identifier for the endpoint." }, "url": { "type": "string", "description": "Where deliveries are POSTed." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ] }, "description": "Which events this endpoint receives." }, "enabled": { "type": "boolean", "description": "Set to false automatically after 20 events in a row fail every attempt. Re-enable with PATCH once the endpoint is fixed." }, "last_success_at": { "nullable": true, "description": "Last delivery your endpoint accepted with a 2xx.", "type": "string" }, "last_failure_at": { "nullable": true, "description": "Last delivery that failed. Check this first when events go quiet.", "type": "string" }, "failure_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Events in a row that failed every attempt. Back to 0 after a delivery succeeds or you re-enable the endpoint. At 20 the endpoint turns itself off." }, "created_at": { "type": "string", "description": "When the endpoint was registered." }, "updated_at": { "type": "string", "description": "Last change to the endpoint, including a change BrokerPlus made, such as turning it off." } }, "required": [ "object", "id", "url", "events", "enabled", "last_success_at", "last_failure_at", "failure_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "description": "Stops delivery immediately, and its delivery log goes with it. Deleting an endpoint that is already gone returns 404.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/changes": { "get": { "operationId": "listChanges", "summary": "List changes since a checkpoint", "description": "Every change to the contacts, leads, deals, tasks, intakes, documents, appointments and communications that the key can read, in the order the changes took effect. BrokerPlus writes each entry in the same database transaction as the change itself, whatever made it: the dashboard, an import, an automation or this API. An entry appears only after its change is committed, and a checkpoint never skips one. Use it as the source of truth for a sync. Webhooks are hints that tell you to call it. Entries are kept for 30 days.", "tags": [ "Changes" ], "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `next_checkpoint` from your last call. Omit it to start at the oldest entry kept. Send `now` to get a checkpoint at the current position and no entries: take it before a full sync from the lists." }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated record types to include: `contact`, `lead`, `deal`, `task`, `intake`, `document`, `appointment`, `communication`. Default: all of them. A checkpoint is valid with the `types` it was issued for, or fewer: reading more types from it would skip their entries, so it is refused with `400 INVALID_CHECKPOINT`. A checkpoint from `after=now` belongs to the `types` sent with it, or to every type when none were sent." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Most entries per page, from 1 to 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "change", "description": "The type of this record. Always `change`.", "type": "string", "enum": [ "change" ] }, "id": { "type": "string", "description": "Identifier of this change entry. Use it to remove duplicates. Do not use it to sort or to resume." }, "record_type": { "type": "string", "enum": [ "contact", "lead", "deal", "task", "intake", "document", "appointment", "communication" ], "description": "The kind of record that changed. Each value names a list endpoint, e.g. `contact` is `/v1/contacts`." }, "record_id": { "type": "string", "description": "Identifier of the record that changed. Read the record to get its current state." }, "action": { "type": "string", "enum": [ "created", "updated", "deleted", "merged", "archived" ], "description": "What happened. `created` and `updated` mean read the record again. `deleted` and `merged` mean remove it from your copy. `archived` means the record left the active book but you can still read it. A restored record comes back as `updated`." }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "Public field names that the change set, for `updated`, `merged` and `archived`. Empty for `created` and `deleted`. Fields that BrokerPlus does not publish are not listed." }, "merged_into_id": { "nullable": true, "description": "For `merged`, the record that this record was merged into. Otherwise null.", "type": "string" }, "occurred_at": { "type": "string", "description": "When BrokerPlus recorded the change, as ISO 8601. Entries are not sorted by it." } }, "required": [ "object", "id", "record_type", "record_id", "action", "changed_fields", "merged_into_id", "occurred_at" ], "additionalProperties": false }, "description": "Changes in the order they took effect. A page can hold fewer entries than `limit`, also none, while `has_more` is true." }, "pagination": { "type": "object", "properties": { "next_checkpoint": { "type": "string", "description": "Send this as `after` on your next call. Store it only after you have applied the page. It is valid for the same `types` only, and for 30 days." }, "has_more": { "type": "boolean", "description": "`true` when more changes are ready now. Call again at once. `false` means wait, then poll again." } }, "required": [ "next_checkpoint", "has_more" ], "additionalProperties": false, "description": "Checkpoint pagination. This envelope replaces the offset pagination of the record lists." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "410": { "description": "`CHECKPOINT_EXPIRED`: the checkpoint is older than 30 days. Get a new one with `after=now`, read every record again from the lists, then poll from the new checkpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List an endpoint's deliveries", "description": "What we sent this endpoint and how it went, newest first: status, attempts, and the last error. Kept for 30 days. With `updated_since` the order is oldest-first, so you can follow deliveries as they settle.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "description": "Only deliveries in this state. `failed` is the list worth retrying." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "webhook_delivery", "description": "The type of this record. Always `webhook_delivery`.", "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "Stable identifier for this delivery. Use it to retry." }, "event_id": { "type": "string", "description": "The event's id - the `bp-delivery-id` header and the body's `id`. The same on every attempt." }, "event_type": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ], "description": "The event that was sent." }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ], "description": "`pending` is queued or between retries. `failed` means every attempt was refused or timed out; retry it once your endpoint is fixed." }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times we have sent it, retries included." }, "last_status_code": { "nullable": true, "description": "The HTTP status your endpoint answered the last attempt with. Null if it never answered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_error": { "nullable": true, "description": "Why the last attempt failed, such as `status 500` or a timeout. Null once delivered.", "type": "string" }, "last_attempt_at": { "nullable": true, "description": "When we last sent it. Null while it waits for its first attempt.", "type": "string" }, "delivered_at": { "nullable": true, "description": "When your endpoint accepted it with a 2xx.", "type": "string" }, "created_at": { "type": "string", "description": "When the event was queued for this endpoint." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to follow deliveries as they settle." } }, "required": [ "object", "id", "event_id", "event_type", "status", "attempts", "last_status_code", "last_error", "last_attempt_at", "delivered_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/webhooks/{id}/deliveries/{delivery_id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a failed delivery", "description": "Sends a `failed` delivery again, with a fresh set of attempts and the same event id, so a receiver that already processed it can dedupe. The endpoint must be enabled.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "webhook_delivery", "description": "The type of this record. Always `webhook_delivery`.", "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string", "description": "Stable identifier for this delivery. Use it to retry." }, "event_id": { "type": "string", "description": "The event's id - the `bp-delivery-id` header and the body's `id`. The same on every attempt." }, "event_type": { "type": "string", "enum": [ "lead.created", "contact.created", "deal.created", "deal.updated", "deal.stage_changed", "deal.status_changed", "deal.funded", "deal.archived", "deal.restored", "condition.created", "condition.satisfied", "task.created", "task.updated", "task.completed", "email.received", "sms.received", "call.logged", "intake.started", "intake.submitted", "intake.document_uploaded", "document.uploaded" ], "description": "The event that was sent." }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ], "description": "`pending` is queued or between retries. `failed` means every attempt was refused or timed out; retry it once your endpoint is fixed." }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times we have sent it, retries included." }, "last_status_code": { "nullable": true, "description": "The HTTP status your endpoint answered the last attempt with. Null if it never answered.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_error": { "nullable": true, "description": "Why the last attempt failed, such as `status 500` or a timeout. Null once delivered.", "type": "string" }, "last_attempt_at": { "nullable": true, "description": "When we last sent it. Null while it waits for its first attempt.", "type": "string" }, "delivered_at": { "nullable": true, "description": "When your endpoint accepted it with a 2xx.", "type": "string" }, "created_at": { "type": "string", "description": "When the event was queued for this endpoint." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to follow deliveries as they settle." } }, "required": [ "object", "id", "event_id", "event_type", "status", "attempts", "last_status_code", "last_error", "last_attempt_at", "delivered_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No such endpoint, or no such delivery on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The delivery is not `failed`, or the endpoint is disabled. Re-enable it with PATCH first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/sandbox/outbox": { "get": { "operationId": "listSandboxOutbox", "summary": "List what a sandbox would have sent", "description": "A sandbox sends no email, no text, no credit request and no lender submission. It records each one here instead, and the call that caused it continues as if it was sent. Newest first. With `updated_since` the order is oldest first, so you can follow the list as your tests run. Works only with a test key (`bp_test_`).", "tags": [ "Sandbox" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only entries recorded at or after it, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "sms", "credit", "lender" ] }, "description": "Only entries on this channel." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "sandbox_outbox_entry", "description": "The type of this record. Always `sandbox_outbox_entry`.", "type": "string", "enum": [ "sandbox_outbox_entry" ] }, "id": { "type": "string", "description": "Stable identifier for this entry." }, "channel": { "type": "string", "enum": [ "email", "sms", "credit", "lender" ], "description": "How it would have gone out. `email` and `sms` are messages. `credit` is a credit report request, answered with the Equifax test file. `lender` is a lender submission, which is recorded and gets no lender answer." }, "adapter": { "type": "string", "description": "The part of BrokerPlus that would have sent it, such as `broker_email` (from the broker's inbox), `system_mail` (a BrokerPlus notification) or `telnyx_sms`." }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "The email addresses or phone numbers it was addressed to." }, "subject": { "nullable": true, "description": "The email subject, or a one-line summary for other channels.", "type": "string" }, "body": { "nullable": true, "description": "The rendered message, or the request as JSON for a credit or lender call. Null when nothing was rendered.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it was about, when the sender named one.", "type": "string" }, "created_at": { "type": "string", "description": "When it would have been sent." } }, "required": [ "object", "id", "channel", "adapter", "recipients", "subject", "body", "deal_id", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key is a live key (`bp_live_`). Use the test key of a sandbox (SANDBOX_ONLY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/audiences": { "get": { "operationId": "listAudiences", "summary": "List audiences", "description": "The saved lists a campaign sends to. An audience is a fixed set of contacts, not a saved filter, so a contact who matches your criteria tomorrow does not join a list you saved today.", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "audience", "description": "The type of this record. Always `audience`.", "type": "string", "enum": [ "audience" ] }, "id": { "type": "string", "description": "Stable identifier for the audience." }, "name": { "type": "string", "description": "The broker's own name for the audience." }, "contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts on it. The list is fixed when you save it." }, "contact_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many contacts are on it." }, "created_at": { "type": "string", "description": "When the audience was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "contact_ids", "contact_count", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAudience", "summary": "Create an audience", "description": "Save a list of contacts to send to. Build the list with `GET /v1/contacts`, and send the ids here. A contact outside your brokerage is refused, and the whole request fails.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Your own name for the audience. Required." }, "contact_ids": { "maxItems": 50000, "type": "array", "items": { "type": "string" }, "description": "The contacts to put on it. A contact outside your brokerage is refused." } }, "required": [ "name", "contact_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "audience", "description": "The type of this record. Always `audience`.", "type": "string", "enum": [ "audience" ] }, "id": { "type": "string", "description": "Stable identifier for the audience." }, "name": { "type": "string", "description": "The broker's own name for the audience." }, "contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts on it. The list is fixed when you save it." }, "contact_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many contacts are on it." }, "created_at": { "type": "string", "description": "When the audience was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "contact_ids", "contact_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as belongs to no team, and cannot own an audience (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "One or more `contact_ids` are not in your brokerage (INVALID_CONTACTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/audiences/{id}": { "patch": { "operationId": "updateAudience", "summary": "Update an audience", "description": "Rename the audience or replace its list of contacts. `contact_ids` replaces the whole list. A campaign that is already scheduled or sending keeps the people it had when it was scheduled.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Your own name for the audience.", "type": "string", "minLength": 1, "maxLength": 120 }, "contact_ids": { "description": "The new list of contacts. It replaces the whole list. A contact outside your brokerage is refused. A campaign that is already scheduled keeps the people it had.", "maxItems": 50000, "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "audience", "description": "The type of this record. Always `audience`.", "type": "string", "enum": [ "audience" ] }, "id": { "type": "string", "description": "Stable identifier for the audience." }, "name": { "type": "string", "description": "The broker's own name for the audience." }, "contact_ids": { "type": "array", "items": { "type": "string" }, "description": "The contacts on it. The list is fixed when you save it." }, "contact_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many contacts are on it." }, "created_at": { "type": "string", "description": "When the audience was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "contact_ids", "contact_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "One or more `contact_ids` are not in your brokerage (INVALID_CONTACTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteAudience", "summary": "Delete an audience", "description": "Deletes the saved list. The contacts stay. A campaign that used the audience keeps its history and its results, and is left with no audience.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns": { "get": { "operationId": "listCampaigns", "summary": "List campaigns", "description": "Every campaign in the brokerage, newest first. Each one carries its result counts, so you can read opens and opt-outs without a second request.", "tags": [ "Campaigns" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ] }, "description": "Return only campaigns in this state." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCampaign", "summary": "Create a campaign draft", "description": "Writes a campaign and leaves it as a draft. Nothing is sent. The broker can open the draft in BrokerPlus and send it, or you can set a time with `POST /v1/campaigns/{id}/schedule`. Write the body in Markdown; `**bold**` and the rest become formatting in the email.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Your own name for the campaign. Clients never see it. Required." }, "channel": { "description": "Defaults to `email`.", "type": "string", "enum": [ "email", "sms" ] }, "subject": { "description": "The email subject line. Required on an email. Can contain variables, the same as `body`.", "type": "string", "minLength": 1, "maxLength": 200 }, "preheader": { "description": "The preview line under the subject in an inbox. Can contain variables, the same as `body`.", "nullable": true, "type": "string", "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The message, as Markdown. `**bold**`, `*italic*`, `[text](https://example.com)`, `#` headings and `-` or `1.` lists become formatting in the email. HTML in this field is shown to the client as text, so write Markdown, not tags. An SMS campaign sends it as plain text with no formatting, and holds 1600 characters. To personalize each message, write a variable as `{{name|fallback}}`, for example `{{borrower.firstName|there}}`. Recipient variables: `borrower.firstName`, `borrower.nickname`, `borrower.lastName`, `borrower.fullName`. Give each recipient variable a fallback, which is sent when the contact has no value; without one, that contact gets a blank. Sender variables: `broker.firstName`, `broker.fullName`, `broker.email`, `broker.phone`, `broker.title`, `broker.bookingLink`, `brokerage.name`, `system.today`. Other variables are rejected." }, "segment_id": { "description": "The audience to send to. Create one with `POST /v1/audiences`.", "nullable": true, "type": "string" }, "segment_ids": { "description": "More audiences to send to, up to 20, together with `segment_id`. A person in more than one audience gets one message. On a change, the two together replace every audience the draft had.", "maxItems": 20, "type": "array", "items": { "type": "string" } } }, "required": [ "name", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as belongs to no team, and cannot own a campaign (NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "`segment_id` or `segment_ids` names an audience that is not in your brokerage (SEGMENT_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns/{id}": { "get": { "operationId": "getCampaign", "summary": "Retrieve a campaign", "description": "One campaign, with the message it sends and its result counts. The counts are recomputed from the recipient rows on every read.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCampaign", "summary": "Update a campaign draft", "description": "Change a draft's name, words or audience. Only the fields you send change. Only a draft can be changed here: a scheduled campaign goes out with the words it has, so change it in BrokerPlus. The channel cannot change.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Your own name for the campaign. Clients never see it. Required." }, "subject": { "description": "The email subject line. Required on an email. Can contain variables, the same as `body`.", "type": "string", "minLength": 1, "maxLength": 200 }, "preheader": { "description": "The preview line under the subject in an inbox. Can contain variables, the same as `body`.", "nullable": true, "type": "string", "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The message, as Markdown. `**bold**`, `*italic*`, `[text](https://example.com)`, `#` headings and `-` or `1.` lists become formatting in the email. HTML in this field is shown to the client as text, so write Markdown, not tags. An SMS campaign sends it as plain text with no formatting, and holds 1600 characters. To personalize each message, write a variable as `{{name|fallback}}`, for example `{{borrower.firstName|there}}`. Recipient variables: `borrower.firstName`, `borrower.nickname`, `borrower.lastName`, `borrower.fullName`. Give each recipient variable a fallback, which is sent when the contact has no value; without one, that contact gets a blank. Sender variables: `broker.firstName`, `broker.fullName`, `broker.email`, `broker.phone`, `broker.title`, `broker.bookingLink`, `brokerage.name`, `system.today`. Other variables are rejected." }, "segment_id": { "description": "The audience to send to. Create one with `POST /v1/audiences`.", "nullable": true, "type": "string" }, "segment_ids": { "description": "More audiences to send to, up to 20, together with `segment_id`. A person in more than one audience gets one message. On a change, the two together replace every audience the draft had.", "maxItems": 20, "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The campaign is not a draft (CAMPAIGN_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "`segment_id` names an audience that is not in your brokerage (SEGMENT_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCampaign", "summary": "Delete a campaign", "description": "Deletes the campaign in any state, with its recipient list and results. Deleting a scheduled or sending campaign stops it: nobody else gets it. You cannot undo this.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns/{id}/schedule": { "post": { "operationId": "scheduleCampaign", "summary": "Schedule a campaign", "description": "Schedules a draft campaign now, the same as Schedule in the campaign composer. The recipient list is frozen and the campaign is `scheduled` for `scheduled_at`. A time in the past starts the send now. The broker can still pause or delete it in BrokerPlus before it fires. The response is the campaign. Every email leaves through the broker's own connected mailbox, which its provider caps per day (Google Workspace 2,000, Gmail 500, Microsoft 365 10,000), so read `warnings` in the response and pass anything there on to the broker. A key with the `no_sending` limit gets `403`.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "description": "When the send starts, as an ISO 8601 timestamp. It must be in the future." }, "send_window_days": { "description": "Spread the send across this many days. `1`, the default, releases everyone on the first day, paced through it. Paced sends only go out between 8 AM and 8 PM, on each recipient's own clock when their address places them and on the campaign creator's otherwise, so a `scheduled_at` outside those hours starts at the next 8 AM. About 150 a day is the safe pace for one mailbox.", "type": "integer", "minimum": 1, "maximum": 365 }, "express_send": { "description": "Send to the whole audience within about two hours of `scheduled_at` (longer for lists over about 700, at the same rate), and ignore `send_window_days`. This queues every recipient at once and releases them from the broker's own mailbox within minutes of each other, so a large audience can use up most of that mailbox's daily sending limit in one go. Confirm the audience size with the broker before setting it. Express sends at any hour, so pick a daytime `scheduled_at`. A fast send from one mailbox is more likely to go to spam, so leave this off unless speed matters more than delivery.", "type": "boolean" }, "skip_weekends": { "description": "Hold the paced send over Saturday and Sunday in the broker's time zone and carry on Monday at 8 AM. Ignored with `express_send`. Defaults to `false`.", "type": "boolean" }, "recurrence": { "description": "Repeat the campaign on this cadence. Omit it for a one-off send.", "nullable": true, "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "recurrence_until": { "description": "The last day an occurrence can start, as an ISO 8601 timestamp. Omit it to repeat until you stop it.", "nullable": true, "type": "string" } }, "required": [ "scheduled_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as cannot send from the connected inbox (NO_INBOX_SEND or FORBIDDEN), or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The campaign is not a draft (CAMPAIGN_LOCKED), it is a follow-up that goes out with the campaign it follows (NOT_A_ROOT), it has follow-ups and the request sets a `recurrence` (FOLLOW_UPS_WITH_RECURRENCE), or it could not be scheduled at this time, for example because it is already going out (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The audience resolves to nobody (EMPTY_SEGMENT), the brokerage has no CASL sender identity (ORG_IDENTITY_INCOMPLETE), an SMS campaign has no phone number (SMS_NOT_CONNECTED), or the message uses a detail of yours that your profile leaves empty, such as `{{broker.phone}}` (SENDER_DETAIL_MISSING).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns/{id}/pause": { "post": { "operationId": "pauseCampaign", "summary": "Pause a campaign", "description": "Stops a campaign that is sending. Nobody else gets it until the broker resumes it in BrokerPlus. Resuming is not on the API, because it starts writing to clients again.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The campaign is not sending (NOT_SENDING).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns/{id}/duplicate": { "post": { "operationId": "duplicateCampaign", "summary": "Duplicate a campaign", "description": "Makes a new draft with the same words, audience and follow-ups. Nothing is sent. Duplicating a follow-up copies the campaign it follows.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "campaign", "description": "The type of this record. Always `campaign`.", "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "description": "Stable identifier for the campaign." }, "name": { "type": "string", "description": "The broker's own name for the campaign. Clients never see it." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the campaign goes out." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent", "failed" ], "description": "Where the campaign is. A campaign that the API creates is `draft`, and a broker moves it forward in BrokerPlus." }, "subject": { "nullable": true, "description": "The email subject line. Null on an SMS campaign.", "type": "string" }, "preheader": { "nullable": true, "description": "The preview line under the subject in an inbox. Null when not set.", "type": "string" }, "body": { "type": "string", "description": "The message. An email campaign returns the HTML that is mailed, because that is what BrokerPlus stores. An SMS campaign returns the plain text." }, "body_markdown": { "nullable": true, "description": "An email campaign's body as Markdown that gives exactly the HTML in `body`. Send it back as `body` to keep the message the same. Null when the HTML has no Markdown form, for example a campaign written in BrokerPlus, and on an SMS campaign.", "type": "string" }, "segment_id": { "nullable": true, "description": "The first audience it sends to. Null when no audience is chosen yet. Read `segment_ids` for every audience.", "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Every audience it sends to. A person in more than one audience, or two contacts with the same email address or phone number, gets one message. Empty when no audience is chosen yet." }, "scheduled_at": { "nullable": true, "description": "When the send starts. Null on a draft.", "type": "string" }, "send_window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days the send is spread across. `1` sends everything at once." }, "express_send": { "type": "boolean", "description": "True when the whole audience goes out within about two hours of the start, instead of paced over days." }, "skip_weekends": { "type": "boolean", "description": "True when the paced send holds over Saturday and Sunday and carries on Monday at 8 AM." }, "recurrence": { "nullable": true, "description": "How often the campaign repeats. Null for a one-off campaign.", "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly" ] }, "occurrence_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which occurrence of a repeating campaign this is. `1` for a one-off." }, "follow_up_of": { "nullable": true, "description": "Set when this campaign is a follow-up: the id of the campaign (or earlier follow-up) it follows. Null on an original campaign.", "type": "string" }, "follow_up_delay_days": { "nullable": true, "description": "How many days after each person's previous message this follow-up goes out. Null on an original campaign.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "follow_up_root_id": { "nullable": true, "description": "On a follow-up: the original campaign of the sequence. Null on an original campaign.", "type": "string" }, "follow_up_step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where this campaign sits in its sequence: `0` on the original, `1` on the first follow-up, and so on." }, "follow_up_audience": { "nullable": true, "description": "Who a follow-up goes to: `no_reply` is everyone who did not reply, `no_open` everyone who did not open. Null on an original campaign.", "type": "string", "enum": [ "no_reply", "no_open" ] }, "series_id": { "nullable": true, "description": "Groups every occurrence of one repeating campaign. Null on a one-off campaign.", "type": "string" }, "started_at": { "nullable": true, "description": "When the send started. Null until it does.", "type": "string" }, "paused_at": { "nullable": true, "description": "When the send was paused. Null while it is not paused.", "type": "string" }, "auto_paused_reason": { "nullable": true, "description": "Why BrokerPlus paused the send by itself: too many unsubscribes, too many suppressed addresses, or the mailbox failing to send. Null when a broker paused it, or it is not paused.", "type": "string", "enum": [ "high_unsubscribe_rate", "high_suppression_rate", "mailbox_send_failures" ] }, "failure_reason": { "nullable": true, "description": "Why the send failed, as a short code such as `sms_not_configured`. Null unless `status` is `failed`.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the send finished. Null until it does.", "type": "string" }, "results": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients on this campaign." }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients that have not been sent to yet." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the message reached." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients the send failed for." }, "bounced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hard bounces. Always `0` when the send goes out of a broker's own mailbox." }, "unsubscribed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opted out. They are skipped from then on, everywhere." }, "suppressed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients skipped at send time, because they had opted out or were on the suppression list." }, "opened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recipients who opened the message. Counted once per person, on the first open." } }, "required": [ "total", "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed", "opened" ], "additionalProperties": false, "description": "Counts per recipient outcome, recomputed from the recipient rows." }, "warnings": { "description": "Only on the response of `POST /v1/campaigns/{id}/schedule`: things the broker must know about the send, in plain sentences. For example, a day close to the daily sending limit of the connected mailbox. Pass each one on to the broker.", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "description": "When the campaign was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "status", "subject", "preheader", "body", "body_markdown", "segment_id", "segment_ids", "scheduled_at", "send_window_days", "express_send", "skip_weekends", "recurrence", "occurrence_number", "follow_up_of", "follow_up_delay_days", "follow_up_root_id", "follow_up_step", "follow_up_audience", "series_id", "started_at", "paused_at", "auto_paused_reason", "failure_reason", "sent_at", "results", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts/{id}/send": { "post": { "operationId": "sendDraft", "summary": "Send a draft", "description": "Sends a draft that waits for review now, as it is written, the same as Send in the broker's drafts folder. The response is the draft, with `status` `sent`, or `scheduled` when the draft has a send time. A key with the `no_sending` limit gets `403`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The draft is no longer waiting for review (DRAFT_LOCKED), the brokerage has no connected email inbox (NO_EMAIL_INBOX), or the automation that wrote it was stopped (AUTOMATION_STOPPED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts/{id}/schedule": { "post": { "operationId": "scheduleDraft", "summary": "Schedule a draft", "description": "Sets a draft that waits for review to go out at `send_at`, the same as Schedule in the broker's drafts folder. A draft that is already `scheduled` moves to the new time. It goes out without anybody pressing Send, so a key with the `no_sending` limit gets `403`. Stop it with `POST /drafts/{id}/unschedule`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_at": { "type": "string", "description": "When the draft goes out, as an ISO 8601 timestamp in the future. A draft that is already `scheduled` moves to this time." } }, "required": [ "send_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The draft was sent, discarded, or is sending now (DRAFT_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts/{id}/unschedule": { "post": { "operationId": "unscheduleDraft", "summary": "Stop a scheduled draft", "description": "Takes a `scheduled` draft back to `pending_review`, so it does not go out. It keeps its time: sending it with `POST /drafts/{id}/send` schedules it for that time again, unless the time has passed.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The draft is not scheduled, or it is sending now (DRAFT_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/drafts/{id}/discard": { "post": { "operationId": "discardDraft", "summary": "Discard a draft", "description": "Discards a draft that waits for review, the same as Discard in the broker's drafts folder. It stays in the list as `discarded` and can no longer be sent. You cannot undo this.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why the draft is discarded. The broker sees it on the draft.", "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The draft is no longer waiting for review (DRAFT_LOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/reply": { "post": { "operationId": "replyToCommunication", "summary": "Reply to a message", "description": "Answers an email or text in its own conversation, as Reply, Reply All or Forward does in the inbox: from the mailbox or number the conversation is on, with the conversation's subject, so the client's mail program shows it in the same thread. Set `send_at` to send it later. The reply is the broker's own: it is in their drafts folder as `sent` (or `scheduled`), and in Sent. The response is `201` with the draft. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "default": "reply", "description": "`reply` answers the sender. `reply_all` also addresses everyone the message was sent to and copied, except the mailbox the reply leaves from. `forward` sends the message on to the addresses in `to`, quoted below `body`. A text takes `reply` only. Answering a message the broker sent goes to the people it was sent to.", "type": "string", "enum": [ "reply", "reply_all", "forward" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The text the client reads, above any forwarded message. Plain text. A text over 1600 characters is refused." }, "body_html": { "description": "A formatted version of an email body. Leave it out to send `body` as written. Not accepted for a text, or for a forward.", "type": "string", "maxLength": 200000 }, "subject": { "description": "Leave it out to keep the conversation's subject, starting `Re:` or `Fwd:`. A different subject can make the client's mail program show the reply as a new conversation. Not accepted for a text.", "type": "string", "minLength": 1, "maxLength": 500 }, "to": { "description": "Who the email goes to. Required for `forward`. For `reply` and `reply_all`, leave it out to use the addresses the mode picks, or send it to replace them. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "cc": { "description": "Addresses to copy on the email. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "bcc": { "description": "Addresses to blind-copy on the email. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "attachments": { "description": "Files the email carries, at most 10. Not accepted for a text.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `rates.pdf`." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, GIF, TIFF, WebP, Word, Excel, PowerPoint, CSV, or plain text." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding, and 25 MB for all the files of one email." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } }, "include_attachments": { "description": "For `forward` only. The forward carries the files of the email it forwards, before any in `attachments`. Set it to `false` to forward the text only. A picture shown inside the email body is not sent as a file.", "type": "boolean" }, "send_at": { "type": "string", "description": "When the message goes out, as an ISO 8601 timestamp in the future. Leave it out to send now. Until then the draft is `scheduled`: move it with `POST /drafts/{id}/schedule`, or stop it with `POST /drafts/{id}/unschedule`." } }, "required": [ "mode", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `mode` a text does not take, a forward with no `to`, a field a text does not take, or a file BrokerPlus cannot send (VALIDATION_ERROR). The message has no address to answer (NO_RECIPIENTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The conversation is on an inbox or number the broker your key acts as cannot send from (THREAD_VIEW_ONLY). The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker your key acts as has no connected mailbox (EMAIL_NOT_CONNECTED) or no phone number (SMS_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/communications/{id}/drafts": { "post": { "operationId": "createReplyDraft", "summary": "Draft a reply to a message", "description": "Writes a reply, reply-all or forward into the drafts of the broker your key acts as, in the message's conversation, and sends it to nobody. The broker finds it under the conversation in their inbox and in their drafts folder, and sends, edits or discards it there. You can also change it with `PATCH /drafts/{id}` and send it with `POST /drafts/{id}/send`.", "tags": [ "Communications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "default": "reply", "description": "`reply` answers the sender. `reply_all` also addresses everyone the message was sent to and copied, except the mailbox the reply leaves from. `forward` sends the message on to the addresses in `to`, quoted below `body`. A text takes `reply` only. Answering a message the broker sent goes to the people it was sent to.", "type": "string", "enum": [ "reply", "reply_all", "forward" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The text the client reads, above any forwarded message. Plain text. A text over 1600 characters is refused." }, "body_html": { "description": "A formatted version of an email body. Leave it out to send `body` as written. Not accepted for a text, or for a forward.", "type": "string", "maxLength": 200000 }, "subject": { "description": "Leave it out to keep the conversation's subject, starting `Re:` or `Fwd:`. A different subject can make the client's mail program show the reply as a new conversation. Not accepted for a text.", "type": "string", "minLength": 1, "maxLength": 500 }, "to": { "description": "Who the email goes to. Required for `forward`. For `reply` and `reply_all`, leave it out to use the addresses the mode picks, or send it to replace them. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "cc": { "description": "Addresses to copy on the email. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "bcc": { "description": "Addresses to blind-copy on the email. Not accepted for a text.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address." }, "name": { "description": "The name shown beside the address.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } }, "attachments": { "description": "Files the email carries, at most 10. Not accepted for a text.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `rates.pdf`." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, GIF, TIFF, WebP, Word, Excel, PowerPoint, CSV, or plain text." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding, and 25 MB for all the files of one email." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } }, "include_attachments": { "description": "For `forward` only. The forward carries the files of the email it forwards, before any in `attachments`. Set it to `false` to forward the text only. A picture shown inside the email body is not sent as a file.", "type": "boolean" } }, "required": [ "mode", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "draft", "description": "The type of this record. Always `draft`.", "type": "string", "enum": [ "draft" ] }, "id": { "type": "string", "description": "Stable identifier for the draft." }, "contact_id": { "nullable": true, "description": "The contact the message is addressed to. Null for a reply or forward to an address that is not a contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the message is about, if any.", "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ], "description": "How the message goes out when it is sent." }, "status": { "type": "string", "enum": [ "pending_review", "scheduled", "sent", "discarded", "failed" ], "description": "`pending_review` until somebody sends or rejects it. `scheduled` when it is set to go out later. `sent` when it went out. `discarded` when the broker rejected it. `failed` when a scheduled send did not go out. A new draft is always `pending_review`. To send it as written, call `POST /v1/drafts/{id}/send`." }, "subject": { "nullable": true, "description": "The subject line. Always `null` for `sms`. After the broker edits the draft, the edited text.", "type": "string" }, "body": { "type": "string", "description": "The message text. Before review, exactly as filed. After the broker edits and sends it, what was sent." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when it has one. Always `null` for `sms`.", "type": "string" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "A contact the message is addressed to." }, "name": { "nullable": true, "description": "That contact's name. Null when the contact has no name on file.", "type": "string" } }, "required": [ "contact_id", "name" ], "additionalProperties": false }, "description": "Who the message is addressed to." }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is sent to. Empty for a text, and for an email filed to a contact." }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is copied to." }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address." }, "name": { "nullable": true, "description": "The name shown beside the address. Null when there is none.", "type": "string" } }, "required": [ "email", "name" ], "additionalProperties": false }, "description": "The email addresses the message is blind-copied to." }, "reply_to_communication_id": { "nullable": true, "description": "The message this draft answers or forwards. It is sent in the same conversation. Read it with `GET /communications/{id}`. Null for a new message.", "type": "string" }, "forward": { "type": "boolean", "description": "True when the draft forwards `reply_to_communication_id` rather than answering it." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The name the file has in the email." }, "content_type": { "nullable": true, "description": "The media type of the file.", "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the file, in bytes." } }, "required": [ "file_name", "content_type", "size" ], "additionalProperties": false }, "description": "The files the email carries." }, "sender_user_id": { "nullable": true, "description": "The broker whose review queue holds the draft, and who it goes out as. Resolve it with `GET /users/{id}`.", "type": "string" }, "sender_name": { "nullable": true, "description": "The name of the broker the message goes out as. Null when `sender_user_id` is null.", "type": "string" }, "created_by_user_id": { "nullable": true, "description": "The broker whose key filed the draft. Null when BrokerPlus has no record of who filed it.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When a `scheduled` draft goes out. Null otherwise.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the draft was sent or rejected. Null while it waits.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who sent or rejected the draft. Null while it waits.", "type": "string" }, "rejection_reason": { "nullable": true, "description": "Why the broker rejected it, when they said. Null on any draft that was not `discarded`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message that went out, once `sent`. Read it with `GET /communications/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the draft was filed." }, "updated_at": { "type": "string", "description": "When the draft last changed." } }, "required": [ "object", "id", "contact_id", "deal_id", "channel", "status", "subject", "body", "body_html", "recipients", "to", "cc", "bcc", "reply_to_communication_id", "forward", "attachments", "sender_user_id", "sender_name", "created_by_user_id", "scheduled_at", "reviewed_at", "reviewed_by_user_id", "rejection_reason", "communication_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `mode` a text does not take, a forward with no `to`, a field a text does not take, or a file BrokerPlus cannot send (VALIDATION_ERROR). The message has no address to answer (NO_RECIPIENTS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The conversation is on an inbox or number the broker your key acts as cannot send from (THREAD_VIEW_ONLY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The message is not in a mailbox that the broker your key acts as can act in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automation-runs": { "get": { "operationId": "listAutomationRuns", "summary": "List automation runs", "description": "The runs of your brokerage's automations, newest first, or oldest first with `updated_since`. A run is one automation working through its steps for one deal or contact.", "tags": [ "Automations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "automation_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the runs of this automation." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the runs about this deal. Send `deal_id` or `contact_id`, not both." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the runs about this contact." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "running", "needs_attention", "succeeded", "partially_succeeded", "skipped", "failed", "canceled" ] }, "description": "Return only runs in this state." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_run", "description": "The type of this record. Always `automation_run`.", "type": "string", "enum": [ "automation_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "automation_id": { "type": "string", "description": "The automation that started the run." }, "automation_name": { "type": "string", "description": "That automation's name." }, "status": { "type": "string", "enum": [ "scheduled", "running", "needs_attention", "succeeded", "partially_succeeded", "skipped", "failed", "canceled" ], "description": "`scheduled`: waiting to start. Only a scheduled run can be started or cancelled through the API. `running`: its steps are under way. The others are final, except `needs_attention`, which waits for the broker." }, "subject_type": { "type": "string", "enum": [ "deal", "contact", "lead" ], "description": "What the run is about." }, "subject_id": { "type": "string", "description": "The id of the deal, contact, or lead." }, "owner_user_id": { "nullable": true, "description": "The user the run's messages go out as.", "type": "string" }, "fired_at": { "type": "string", "description": "When the automation matched this deal or contact." }, "created_at": { "type": "string", "description": "When the run was created." }, "updated_at": { "type": "string", "description": "When the run last changed." } }, "required": [ "object", "id", "automation_id", "automation_name", "status", "subject_type", "subject_id", "owner_user_id", "fired_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automation-runs/{id}": { "get": { "operationId": "getAutomationRun", "summary": "Retrieve an automation run", "description": "One automation run and its state.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_run", "description": "The type of this record. Always `automation_run`.", "type": "string", "enum": [ "automation_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "automation_id": { "type": "string", "description": "The automation that started the run." }, "automation_name": { "type": "string", "description": "That automation's name." }, "status": { "type": "string", "enum": [ "scheduled", "running", "needs_attention", "succeeded", "partially_succeeded", "skipped", "failed", "canceled" ], "description": "`scheduled`: waiting to start. Only a scheduled run can be started or cancelled through the API. `running`: its steps are under way. The others are final, except `needs_attention`, which waits for the broker." }, "subject_type": { "type": "string", "enum": [ "deal", "contact", "lead" ], "description": "What the run is about." }, "subject_id": { "type": "string", "description": "The id of the deal, contact, or lead." }, "owner_user_id": { "nullable": true, "description": "The user the run's messages go out as.", "type": "string" }, "fired_at": { "type": "string", "description": "When the automation matched this deal or contact." }, "created_at": { "type": "string", "description": "When the run was created." }, "updated_at": { "type": "string", "description": "When the run last changed." } }, "required": [ "object", "id", "automation_id", "automation_name", "status", "subject_type", "subject_id", "owner_user_id", "fired_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automation-runs/{id}/steps": { "get": { "operationId": "listAutomationRunSteps", "summary": "List an automation run's steps", "description": "What each step of the run did or will do, in the order they fall due, as the run panel in BrokerPlus shows it: the draft it wrote, the message it sent, the task it made, or why it was skipped or stopped.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_run_step", "description": "The type of this record. Always `automation_run_step`.", "type": "string", "enum": [ "automation_run_step" ] }, "id": { "type": "string", "description": "Stable identifier for this step of the run." }, "run_id": { "type": "string", "description": "The run the step belongs to." }, "step_id": { "type": "string", "description": "The automation's step that this carries out. See `steps` on `GET /v1/automations/{id}`." }, "kind": { "type": "string", "description": "What the step does, such as `send_email` or `create_task`. The automation step's `kind`." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step sits in the automation, from 0." }, "status": { "type": "string", "enum": [ "scheduled", "preparing", "awaiting_review", "awaiting_event", "queued", "sending", "needs_attention", "succeeded", "suppressed", "skipped", "failed", "canceled" ], "description": "`scheduled` waits for `target_at`. `awaiting_review` is a draft for the broker to approve. `awaiting_event` waits for the client to do something, such as reply. `needs_attention` stopped until the broker fixes it. `suppressed` and `skipped` did not run, and `reason` says why. `succeeded`, `failed`, and `canceled` are final." }, "reason": { "nullable": true, "description": "Why the step is skipped, suppressed, failed, or needs attention, in words.", "type": "string" }, "recipient_contact_id": { "nullable": true, "description": "The contact the step reaches, for a step that writes to somebody. Null for a colleague, a typed address, or no recipient.", "type": "string" }, "recipient_user_id": { "nullable": true, "description": "The colleague the step writes to, when it writes to a broker in the brokerage rather than a contact.", "type": "string" }, "sender_user_id": { "nullable": true, "description": "The user a message goes out as. Null for a step that sends nothing.", "type": "string" }, "assignee_user_id": { "nullable": true, "description": "The user a task or event is for. Null when the step makes neither.", "type": "string" }, "target_at": { "type": "string", "description": "When the step is due to happen." }, "prepare_at": { "type": "string", "description": "When BrokerPlus starts to prepare it, such as writing the draft." }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times BrokerPlus has tried the step, from 1." }, "draft_id": { "nullable": true, "description": "The draft the step wrote. Read it with `GET /v1/drafts/{id}`.", "type": "string" }, "communication_id": { "nullable": true, "description": "The message the step sent. Read it with `GET /v1/communications/{id}`.", "type": "string" }, "task_id": { "nullable": true, "description": "The task the step made. Read it with `GET /v1/tasks/{id}`.", "type": "string" }, "calendar_event_id": { "nullable": true, "description": "The calendar event the step made. Read it with `GET /v1/appointments/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the step was planned." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "run_id", "step_id", "kind", "position", "status", "reason", "recipient_contact_id", "recipient_user_id", "sender_user_id", "assignee_user_id", "target_at", "prepare_at", "attempt", "draft_id", "communication_id", "task_id", "calendar_event_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The run does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automation-runs/{id}/start": { "post": { "operationId": "startAutomationRun", "summary": "Start an automation run now", "description": "Starts a `scheduled` run now instead of at its time, the same as Run now on the run in BrokerPlus. Its steps can reach the client. The response is the run. Read what each step did with `GET /v1/automation-runs/{id}/steps`. A key with the `no_sending` limit gets `403`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_run", "description": "The type of this record. Always `automation_run`.", "type": "string", "enum": [ "automation_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "automation_id": { "type": "string", "description": "The automation that started the run." }, "automation_name": { "type": "string", "description": "That automation's name." }, "status": { "type": "string", "enum": [ "scheduled", "running", "needs_attention", "succeeded", "partially_succeeded", "skipped", "failed", "canceled" ], "description": "`scheduled`: waiting to start. Only a scheduled run can be started or cancelled through the API. `running`: its steps are under way. The others are final, except `needs_attention`, which waits for the broker." }, "subject_type": { "type": "string", "enum": [ "deal", "contact", "lead" ], "description": "What the run is about." }, "subject_id": { "type": "string", "description": "The id of the deal, contact, or lead." }, "owner_user_id": { "nullable": true, "description": "The user the run's messages go out as.", "type": "string" }, "fired_at": { "type": "string", "description": "When the automation matched this deal or contact." }, "created_at": { "type": "string", "description": "When the run was created." }, "updated_at": { "type": "string", "description": "When the run last changed." } }, "required": [ "object", "id", "automation_id", "automation_name", "status", "subject_type", "subject_id", "owner_user_id", "fired_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus: they cannot send from the connected inbox, or their broker reviews what goes to clients (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The run is not `scheduled` (RUN_NOT_SCHEDULED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automation-runs/{id}/cancel": { "post": { "operationId": "cancelAutomationRun", "summary": "Cancel an automation run", "description": "Removes a `scheduled` run before it starts. This only stops messages. A run that has started is not cancelled here; the broker stops its steps in BrokerPlus.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The run has already started (RUN_NOT_SCHEDULED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/campaigns/{id}/recipients": { "get": { "operationId": "listCampaignRecipients", "summary": "List a campaign's recipients", "description": "Who the campaign reached, and what each person did. `opened_at` is the open, and `unsubscribed` is the opt-out. Clicks are not recorded: BrokerPlus does not rewrite the links in your message, so no endpoint reports them.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed" ] }, "description": "Return only recipients with this outcome." }, { "name": "opened", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Send `true` for only the people who opened the message, or `false` for only those who did not." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "campaign_recipient", "description": "The type of this record. Always `campaign_recipient`.", "type": "string", "enum": [ "campaign_recipient" ] }, "id": { "type": "string", "description": "Stable identifier for this recipient row." }, "campaign_id": { "type": "string", "description": "The campaign it belongs to." }, "contact_id": { "type": "string", "description": "The contact. Resolve against `GET /v1/contacts/{id}`." }, "status": { "type": "string", "enum": [ "queued", "sent", "failed", "bounced", "unsubscribed", "suppressed" ], "description": "What happened for this person. `suppressed` means the send was skipped because they had opted out." }, "scheduled_for": { "nullable": true, "description": "When this person's message is released. Null means immediately.", "type": "string" }, "sent_at": { "nullable": true, "description": "When the message went out. Null until it does.", "type": "string" }, "opened_at": { "nullable": true, "description": "When this person first opened the message. Null when they have not.", "type": "string" }, "unsubscribed": { "type": "boolean", "description": "`true` when this person opted out. They are skipped from then on, everywhere." }, "created_at": { "type": "string", "description": "When the recipient was added to the campaign." }, "updated_at": { "type": "string", "description": "Last change to this recipient, such as a send or an open." } }, "required": [ "object", "id", "campaign_id", "contact_id", "status", "scheduled_for", "sent_at", "opened_at", "unsubscribed", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/custom-fields": { "get": { "operationId": "listContactCustomFields", "summary": "List a contact's custom fields", "description": "Every custom field the brokerage keeps on a contact, with this contact's value. A field that nobody has answered returns a `value` of `null`, so the list is the same length on every contact.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/custom-fields/{key}": { "patch": { "operationId": "setContactCustomField", "summary": "Set a custom field on a contact", "description": "Sets one field by its `key`. The write is idempotent: the same request twice leaves the same value. Send an empty string to clear the field, which makes it unanswered again.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to store, as text. A `short_text` field takes one line of 200 characters or fewer, and line breaks change to spaces. A `number`,`money` or `percent` field takes a number like `1200` or `4.5`, a `date` field takes `YYYY-MM-DD`, a `checkbox` takes `true` or `false`, a `url` takes a full web address, a `select` field takes one of its options, and a `multi_select` field takes a JSON array of its options, like `[\"Appraisal\",\"Insurance\"]`. Send an empty string to clear the field." } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable slug for the field. Use it to read and to write. A rename does not change it." }, "label": { "type": "string", "description": "What the brokerage calls the field on screen." }, "type": { "type": "string", "enum": [ "short_text", "text", "number", "money", "percent", "date", "checkbox", "select", "multi_select", "url" ], "description": "What the field holds. New types may be added; treat one you do not recognize as text you can read but should not write." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values on a `select` or `multi_select` field. Empty on every other type." }, "section": { "type": "string", "description": "The group the field is shown under." }, "value": { "nullable": true, "description": "The value on this contact or deal, as text. Null when nobody has answered the field yet.", "type": "string" } }, "required": [ "key", "label", "type", "options", "section", "value" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The value does not fit the field's type or its options (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No live field has that `key` on a contact (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/templates/merge-fields": { "get": { "operationId": "listTemplateMergeFields", "summary": "List merge fields", "description": "Every merge field a template can use, including your brokerage's own custom fields. Write one in a subject or a body as `{{name}}`, or as `{{name|fallback}}` when the file can be without the value.", "tags": [ "Templates" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Write it between double braces in a subject or a body, for example `{{client.firstName}}`." }, "label": { "type": "string", "description": "The name of the field in the Pulse editor." }, "section": { "type": "string", "description": "The group that the editor shows the field in, for example `Client`, `Property` or `Partners`." }, "format": { "type": "string", "enum": [ "text", "date", "currency", "percent", "phone", "url" ], "description": "How the value is written into the message. A date reads as `July 14, 2026`." }, "example": { "type": "string", "description": "A sample value, as the editor previews it." }, "available_on": { "type": "string", "enum": [ "any", "deal", "meeting_booked" ], "description": "`any`: every automation can fill it. `deal`: only an automation that runs on a deal, for example a stage change. `meeting_booked`: only the automation that runs when a client books a meeting." }, "may_be_empty": { "type": "boolean", "description": "True when a file can correctly have no value, for example a Realtor on a refinance. Give these fields a fallback: `{{name|fallback}}`." } }, "required": [ "name", "label", "section", "format", "example", "available_on", "may_be_empty" ], "additionalProperties": false }, "description": "Every merge field, grouped by section in the order the Pulse editor lists them." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/templates": { "get": { "operationId": "listTemplates", "summary": "List templates", "description": "The email and text templates in the Pulse library that your key's broker can open: the templates of every team they belong to. Sorted by name. With `updated_since`, sorted by last change, oldest first.", "tags": [ "Templates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "sms" ] }, "description": "Return only `email` or only `sms` templates." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set to `true` to include archived templates." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "template", "description": "The type of this record. Always `template`.", "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "name": { "type": "string", "description": "The template's name in the Pulse library. Brokers see it. Clients do not." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "`email` or `sms`. It does not change after you create the template." }, "subject": { "nullable": true, "description": "The email subject line. It can contain merge fields. Always null on an `sms` template.", "type": "string" }, "body": { "type": "string", "description": "The message as plain text, with merge fields written as `{{name}}` or `{{name|fallback}}`. See `GET /v1/templates/merge-fields`." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when one was written in the Pulse editor. Null when the template is plain text.", "type": "string" }, "merge_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The merge field, as written between the braces." }, "fallback": { "nullable": true, "description": "The text used when the file has no value. Null means that the field is required: a message whose file has no value is held for the broker, and is not sent with a gap.", "type": "string" } }, "required": [ "name", "fallback" ], "additionalProperties": false }, "description": "Every merge field that the subject and the body use. BrokerPlus computes the list when the template is saved." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The file name the client sees." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "content_type": { "nullable": true, "description": "MIME type, e.g. `application/pdf`. Null when none was recorded.", "type": "string" } }, "required": [ "file_name", "file_size", "content_type" ], "additionalProperties": false }, "description": "Files that go with every email sent from this template, as real attachments. Empty when there are none. Add them in BrokerPlus." }, "team_id": { "nullable": true, "description": "The broker team that shares the template. Resolve it with `GET /v1/teams/{id}`.", "type": "string" }, "archived_at": { "nullable": true, "description": "When the template was archived. Null while it is in the library.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "subject", "body", "body_html", "merge_fields", "attachments", "team_id", "archived_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`channel` or `updated_since` is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createTemplate", "summary": "Create a template", "description": "Adds an email or text template to the Pulse library of the team your key's broker is working in. A template sends nothing by itself. An automation sends it.", "tags": [ "Templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The template's name in the Pulse library. Required." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "`email` or `sms`. Required. You cannot change it later." }, "subject": { "description": "The email subject line. Required on an `email` template. Do not send it on an `sms` template.", "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "type": "string", "maxLength": 50000, "description": "The message as plain text. Write a merge field as `{{name}}`, or as `{{name|fallback}}` when the file can be without the value. A merge field that `GET /v1/templates/merge-fields` does not list is refused." }, "body_html": { "description": "Optional, `email` only. A formatted version of the body. BrokerPlus removes scripts and unsafe markup before it saves the HTML. Send `body` as the plain-text version of the same message.", "type": "string", "maxLength": 200000 } }, "required": [ "name", "channel", "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "template", "description": "The type of this record. Always `template`.", "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "name": { "type": "string", "description": "The template's name in the Pulse library. Brokers see it. Clients do not." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "`email` or `sms`. It does not change after you create the template." }, "subject": { "nullable": true, "description": "The email subject line. It can contain merge fields. Always null on an `sms` template.", "type": "string" }, "body": { "type": "string", "description": "The message as plain text, with merge fields written as `{{name}}` or `{{name|fallback}}`. See `GET /v1/templates/merge-fields`." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when one was written in the Pulse editor. Null when the template is plain text.", "type": "string" }, "merge_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The merge field, as written between the braces." }, "fallback": { "nullable": true, "description": "The text used when the file has no value. Null means that the field is required: a message whose file has no value is held for the broker, and is not sent with a gap.", "type": "string" } }, "required": [ "name", "fallback" ], "additionalProperties": false }, "description": "Every merge field that the subject and the body use. BrokerPlus computes the list when the template is saved." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The file name the client sees." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "content_type": { "nullable": true, "description": "MIME type, e.g. `application/pdf`. Null when none was recorded.", "type": "string" } }, "required": [ "file_name", "file_size", "content_type" ], "additionalProperties": false }, "description": "Files that go with every email sent from this template, as real attachments. Empty when there are none. Add them in BrokerPlus." }, "team_id": { "nullable": true, "description": "The broker team that shares the template. Resolve it with `GET /v1/teams/{id}`.", "type": "string" }, "archived_at": { "nullable": true, "description": "When the template was archived. Null while it is in the library.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "subject", "body", "body_html", "merge_fields", "attachments", "team_id", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The template is not valid (VALIDATION_ERROR), or it uses a merge field that does not exist (UNKNOWN_MERGE_FIELDS). `details.unknown` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN), or is not working in a team they belong to (NO_TEAM, READ_ONLY_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/templates/{id}": { "get": { "operationId": "getTemplate", "summary": "Read a template", "description": "Returns one email or text template, archived or not, with the merge fields it uses.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "template", "description": "The type of this record. Always `template`.", "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "name": { "type": "string", "description": "The template's name in the Pulse library. Brokers see it. Clients do not." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "`email` or `sms`. It does not change after you create the template." }, "subject": { "nullable": true, "description": "The email subject line. It can contain merge fields. Always null on an `sms` template.", "type": "string" }, "body": { "type": "string", "description": "The message as plain text, with merge fields written as `{{name}}` or `{{name|fallback}}`. See `GET /v1/templates/merge-fields`." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when one was written in the Pulse editor. Null when the template is plain text.", "type": "string" }, "merge_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The merge field, as written between the braces." }, "fallback": { "nullable": true, "description": "The text used when the file has no value. Null means that the field is required: a message whose file has no value is held for the broker, and is not sent with a gap.", "type": "string" } }, "required": [ "name", "fallback" ], "additionalProperties": false }, "description": "Every merge field that the subject and the body use. BrokerPlus computes the list when the template is saved." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The file name the client sees." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "content_type": { "nullable": true, "description": "MIME type, e.g. `application/pdf`. Null when none was recorded.", "type": "string" } }, "required": [ "file_name", "file_size", "content_type" ], "additionalProperties": false }, "description": "Files that go with every email sent from this template, as real attachments. Empty when there are none. Add them in BrokerPlus." }, "team_id": { "nullable": true, "description": "The broker team that shares the template. Resolve it with `GET /v1/teams/{id}`.", "type": "string" }, "archived_at": { "nullable": true, "description": "When the template was archived. Null while it is in the library.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "subject", "body", "body_html", "merge_fields", "attachments", "team_id", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateTemplate", "summary": "Update a template", "description": "Send only the fields you are changing. Every automation that sends this template sends the new copy from its next message.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A new name.", "type": "string", "minLength": 1, "maxLength": 200 }, "subject": { "description": "A new subject line. `email` templates only.", "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "description": "A new plain-text message. When you send `body` without `body_html`, BrokerPlus removes the formatted version.", "type": "string", "maxLength": 50000 }, "body_html": { "description": "A new formatted version, `email` only. Send null to go back to plain text.", "nullable": true, "type": "string", "maxLength": 200000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "template", "description": "The type of this record. Always `template`.", "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "name": { "type": "string", "description": "The template's name in the Pulse library. Brokers see it. Clients do not." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "`email` or `sms`. It does not change after you create the template." }, "subject": { "nullable": true, "description": "The email subject line. It can contain merge fields. Always null on an `sms` template.", "type": "string" }, "body": { "type": "string", "description": "The message as plain text, with merge fields written as `{{name}}` or `{{name|fallback}}`. See `GET /v1/templates/merge-fields`." }, "body_html": { "nullable": true, "description": "The formatted version of an email, when one was written in the Pulse editor. Null when the template is plain text.", "type": "string" }, "merge_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The merge field, as written between the braces." }, "fallback": { "nullable": true, "description": "The text used when the file has no value. Null means that the field is required: a message whose file has no value is held for the broker, and is not sent with a gap.", "type": "string" } }, "required": [ "name", "fallback" ], "additionalProperties": false }, "description": "Every merge field that the subject and the body use. BrokerPlus computes the list when the template is saved." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "description": "The file name the client sees." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Size in bytes." }, "content_type": { "nullable": true, "description": "MIME type, e.g. `application/pdf`. Null when none was recorded.", "type": "string" } }, "required": [ "file_name", "file_size", "content_type" ], "additionalProperties": false }, "description": "Files that go with every email sent from this template, as real attachments. Empty when there are none. Add them in BrokerPlus." }, "team_id": { "nullable": true, "description": "The broker team that shares the template. Resolve it with `GET /v1/teams/{id}`.", "type": "string" }, "archived_at": { "nullable": true, "description": "When the template was archived. Null while it is in the library.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "name", "channel", "subject", "body", "body_html", "merge_fields", "attachments", "team_id", "archived_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The change is not valid (VALIDATION_ERROR), or it uses a merge field that does not exist (UNKNOWN_MERGE_FIELDS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteTemplate", "summary": "Archive a template", "description": "Removes the template from the library. The messages it already sent are kept. Idempotent: archiving an archived template returns 200.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "An automation still sends the template. Remove it from that automation first (TEMPLATE_IN_USE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates": { "get": { "operationId": "listOutreachTemplates", "summary": "List outreach templates", "description": "The first-touch emails and texts a broker sends by hand from the refinance, renewal and lead lanes, as the outreach templates editor lists them: the broker's own set and their team's. A teammate's own templates are not listed.", "tags": [ "Templates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ] }, "description": "Only the templates for this lane and channel." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "personal", "team" ] }, "description": "`personal` for the broker's own set, `team` for the team's." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createOutreachTemplate", "summary": "Create an outreach template", "description": "Adds a template to the broker's own set, or the team's with `scope: team`. It is not the lane's primary until you set it. Nothing is sent.", "tags": [ "Templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The name, at most 80 characters." }, "subject": { "description": "The email subject. If you send no subject and no body, the lane's default copy is used.", "type": "string", "maxLength": 200 }, "body": { "description": "The message, with merge fields.", "type": "string", "maxLength": 20000 }, "is_pre_renewal": { "description": "Make it the pre-renewal email of its set. Only for `renewal_initial`.", "type": "boolean" }, "scope": { "description": "`personal` (the default) or `team`. Only a broker who can send email can write a team template.", "type": "string", "enum": [ "personal", "team" ] } }, "required": [ "kind", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "`is_pre_renewal` is only for `renewal_initial` (INVALID_PRE_RENEWAL_KIND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can write the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The set already has a template with this name in this lane (NAME_CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates/{id}": { "get": { "operationId": "getOutreachTemplate", "summary": "Retrieve an outreach template", "description": "One outreach template.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateOutreachTemplate", "summary": "Update an outreach template", "description": "Changes the template's name, subject, message, or whether it is the pre-renewal email.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The name, at most 80 characters." }, "subject": { "description": "The email subject.", "type": "string", "maxLength": 200 }, "body": { "description": "The message, with merge fields. When you send `body` without `body_html`, BrokerPlus removes the formatted version.", "type": "string", "maxLength": 20000 }, "body_html": { "description": "A new formatted version, email templates only. BrokerPlus removes scripts and unsafe markup before it saves the HTML. Send `body` as the plain-text version of the same message, or null to go back to plain text.", "nullable": true, "type": "string", "maxLength": 200000 }, "is_pre_renewal": { "description": "Make it the pre-renewal email of its set. Only for `renewal_initial`.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can change the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is a teammate's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The set already has a template with this name in this lane (NAME_CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteOutreachTemplate", "summary": "Delete an outreach template", "description": "Deletes the template. If it was the lane's primary, the oldest template left in its set becomes primary. The broker's own set always keeps one template per lane.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "It is the last template in the broker's own set for this lane (LAST_VARIANT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can change the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is a teammate's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates/{id}/set-primary": { "post": { "operationId": "setPrimaryOutreachTemplate", "summary": "Make an outreach template the lane's primary", "description": "The lane starts from this template when the broker sends. The set's other templates in the lane stop being primary.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can change the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is a teammate's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates/{id}/duplicate": { "post": { "operationId": "duplicateOutreachTemplate", "summary": "Duplicate an outreach template", "description": "Copies the template into its own set under a new name. The copy is never primary or pre-renewal.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can add to the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is a teammate's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates/{id}/share": { "post": { "operationId": "shareOutreachTemplate", "summary": "Share an outreach template with the team", "description": "Copies one of the broker's own templates into the team's set, where every teammate can send it.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Nobody else on the team can send email, so there is nobody to share with (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can add to the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is not the broker's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/outreach-templates/{id}/copy-to-personal": { "post": { "operationId": "copyOutreachTemplateToPersonal", "summary": "Copy a team outreach template to the broker's own", "description": "Copies one of the team's templates into the broker's own set, to change without changing what teammates send.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "outreach_template", "description": "The type of this record. Always `outreach_template`.", "type": "string", "enum": [ "outreach_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "kind": { "type": "string", "enum": [ "refinance_initial", "renewal_initial", "leads_initial", "refinance_sms", "renewal_sms", "leads_sms" ], "description": "Which lane and channel the template is for: `refinance_initial`, `renewal_initial` and `leads_initial` are emails; `refinance_sms`, `renewal_sms` and `leads_sms` are texts." }, "scope": { "type": "string", "enum": [ "personal", "team" ], "description": "`personal` is the broker's own. `team` is shared with every teammate who can send." }, "team_id": { "type": "string", "description": "The broker's team, which holds both sets." }, "owner_user_id": { "nullable": true, "description": "The broker who owns a personal template. Null for a team template.", "type": "string" }, "name": { "type": "string", "description": "The template's name. Unique in its set and lane." }, "subject": { "type": "string", "description": "The email subject, with merge fields. Empty for a text." }, "body": { "type": "string", "description": "The message, with merge fields." }, "body_html": { "nullable": true, "description": "The formatted version of an email template, with merge fields, as the broker's editor saves it. Null for a text, or for an email kept as plain text.", "type": "string" }, "is_primary": { "type": "boolean", "description": "True for the template the lane starts from when the broker sends. Each set has one per lane." }, "is_pre_renewal": { "type": "boolean", "description": "True for the renewal email sent before a renewal window opens. At most one per set." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "kind", "scope", "team_id", "owner_user_id", "name", "subject", "body", "body_html", "is_primary", "is_pre_renewal", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Only a broker who can send email can copy the team's templates (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist or is not the team's (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/media-assets": { "get": { "operationId": "listMediaAssets", "summary": "List the media library", "description": "The pictures and video stills the brokerage keeps for its outreach emails, newest first, as the media library in BrokerPlus shows them. Every broker in the brokerage shares one library. Media never changes once added, so this list takes no `updated_since`.", "tags": [ "Templates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "image", "video_link" ] }, "description": "Only pictures (`image`) or only video stills (`video_link`)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "media_asset", "description": "The type of this record. Always `media_asset`.", "type": "string", "enum": [ "media_asset" ] }, "id": { "type": "string", "description": "Stable identifier for the media." }, "kind": { "type": "string", "enum": [ "image", "video_link" ], "description": "`image` an uploaded picture. `video_link` a still of a video with a play button, linking to the video." }, "name": { "type": "string", "description": "The name shown in the media library." }, "mime_type": { "type": "string", "description": "The picture's type: `image/png`, `image/jpeg`, `image/webp` or `image/gif`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The picture's size in bytes." }, "width": { "nullable": true, "description": "Width in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "nullable": true, "description": "Height in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "video_url": { "nullable": true, "description": "The video the still links to. Null for an image.", "type": "string" }, "url": { "type": "string", "description": "The picture's permanent public address, the one an email shows. It does not expire." }, "created_by_user_id": { "nullable": true, "description": "The broker who added it.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "name", "mime_type", "file_size", "width", "height", "video_url", "url", "created_by_user_id", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "uploadMediaImage", "summary": "Add a picture to the media library", "description": "Uploads a picture for outreach emails: PNG, JPEG, WebP or GIF, at most 10 MB and 2000 pixels on its longest side. Send JSON with the file in base64, or `multipart/form-data` with the file in a field named `file`. Its `url` is public, because an email shows it to whoever opens it.", "tags": [ "Templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, e.g. `team-photo.jpg`. The name in the library is the filename without its extension." }, "content_base64": { "type": "string", "minLength": 1, "description": "The picture, in standard base64: PNG, JPEG, WebP or GIF, at most 10 MB and 2000 pixels on its longest side." } }, "required": [ "file_name", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "media_asset", "description": "The type of this record. Always `media_asset`.", "type": "string", "enum": [ "media_asset" ] }, "id": { "type": "string", "description": "Stable identifier for the media." }, "kind": { "type": "string", "enum": [ "image", "video_link" ], "description": "`image` an uploaded picture. `video_link` a still of a video with a play button, linking to the video." }, "name": { "type": "string", "description": "The name shown in the media library." }, "mime_type": { "type": "string", "description": "The picture's type: `image/png`, `image/jpeg`, `image/webp` or `image/gif`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The picture's size in bytes." }, "width": { "nullable": true, "description": "Width in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "nullable": true, "description": "Height in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "video_url": { "nullable": true, "description": "The video the still links to. Null for an image.", "type": "string" }, "url": { "type": "string", "description": "The picture's permanent public address, the one an email shows. It does not expire." }, "created_by_user_id": { "nullable": true, "description": "The broker who added it.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "name", "mime_type", "file_size", "width", "height", "video_url", "url", "created_by_user_id", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is empty (NO_FILE), over 10 MB (FILE_TOO_LARGE), not a supported picture (INVALID_TYPE), or over 2000 pixels on a side (IMAGE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/media-assets/{id}": { "get": { "operationId": "getMediaAsset", "summary": "Retrieve a media library item", "description": "One picture or video still from the media library.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "media_asset", "description": "The type of this record. Always `media_asset`.", "type": "string", "enum": [ "media_asset" ] }, "id": { "type": "string", "description": "Stable identifier for the media." }, "kind": { "type": "string", "enum": [ "image", "video_link" ], "description": "`image` an uploaded picture. `video_link` a still of a video with a play button, linking to the video." }, "name": { "type": "string", "description": "The name shown in the media library." }, "mime_type": { "type": "string", "description": "The picture's type: `image/png`, `image/jpeg`, `image/webp` or `image/gif`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The picture's size in bytes." }, "width": { "nullable": true, "description": "Width in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "nullable": true, "description": "Height in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "video_url": { "nullable": true, "description": "The video the still links to. Null for an image.", "type": "string" }, "url": { "type": "string", "description": "The picture's permanent public address, the one an email shows. It does not expire." }, "created_by_user_id": { "nullable": true, "description": "The broker who added it.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "name", "mime_type", "file_size", "width", "height", "video_url", "url", "created_by_user_id", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteMediaAsset", "summary": "Delete a media library item", "description": "Removes the picture or video still from the library. An email already sent that shows it shows a broken picture from then on.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The item does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/media-assets/video-links": { "post": { "operationId": "createMediaVideoLink", "summary": "Add a video to the media library", "description": "Adds a still of the video with a play button on it, linking to the video, for outreach emails. BrokerPlus fetches the still from the video's site; Instagram and Facebook get a branded card instead.", "tags": [ "Templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "An HTTPS link to a YouTube, Vimeo, Loom, NeetoRecord, Instagram or Facebook video." }, "name": { "description": "The name in the library. Leave it out and BrokerPlus uses the video's title.", "type": "string", "maxLength": 120 } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "media_asset", "description": "The type of this record. Always `media_asset`.", "type": "string", "enum": [ "media_asset" ] }, "id": { "type": "string", "description": "Stable identifier for the media." }, "kind": { "type": "string", "enum": [ "image", "video_link" ], "description": "`image` an uploaded picture. `video_link` a still of a video with a play button, linking to the video." }, "name": { "type": "string", "description": "The name shown in the media library." }, "mime_type": { "type": "string", "description": "The picture's type: `image/png`, `image/jpeg`, `image/webp` or `image/gif`." }, "file_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The picture's size in bytes." }, "width": { "nullable": true, "description": "Width in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "nullable": true, "description": "Height in pixels, when it could be read.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "video_url": { "nullable": true, "description": "The video the still links to. Null for an image.", "type": "string" }, "url": { "type": "string", "description": "The picture's permanent public address, the one an email shows. It does not expire." }, "created_by_user_id": { "nullable": true, "description": "The broker who added it.", "type": "string" }, "created_at": { "type": "string", "description": "When it was added." } }, "required": [ "object", "id", "kind", "name", "mime_type", "file_size", "width", "height", "video_url", "url", "created_by_user_id", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The link is not an HTTPS link to a supported video site (UNSUPPORTED_VIDEO).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The video's site did not give a still (THUMBNAIL_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/catalog": { "get": { "operationId": "getAutomationCatalog", "summary": "Read the automation catalog", "description": "Everything an automation can be built from, as the app's builder offers it: each event that starts one and its `config`, each kind of step and its `params`, who a message can go to, the fields a check can compare (with the brokerage's custom fields), and the node kinds of a `graph`. Read it before you build an automation.", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The value of `type` on an automation." }, "label": { "type": "string", "description": "The name of the event on screen." }, "description": { "type": "string", "description": "When it starts, in a sentence or two." }, "subject": { "type": "string", "enum": [ "deal", "contact", "lead" ], "description": "What a run is about: a deal, a contact, or a lead." }, "starts_from": { "type": "string", "enum": [ "event", "date" ], "description": "`event` starts when something happens. `date` starts from a date, checked each day." }, "config": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The key in `config`." }, "required": { "type": "boolean", "description": "True when the type cannot be saved without it." }, "description": { "type": "string", "description": "What it does and what to send." } }, "required": [ "key", "required", "description" ], "additionalProperties": false }, "description": "The settings the type takes in `config`." }, "step_kinds": { "type": "array", "items": { "type": "string" }, "description": "The step kinds this type accepts." }, "auto_send_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "description": "The message steps that can send with no review (`ask_before_sending: false`) on this type." } }, "required": [ "type", "label", "description", "subject", "starts_from", "config", "step_kinds", "auto_send_channels" ], "additionalProperties": false }, "description": "Every event that can start an automation." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "The value of `kind` on a step." }, "label": { "type": "string", "description": "The name of the step on screen." }, "description": { "type": "string", "description": "What the step does." }, "group": { "type": "string", "description": "Where the builder lists it, for example `Communication`." }, "reaches_client": { "type": "boolean", "description": "True when the step can reach a client. A key with the `no_sending` limit cannot turn on an automation with one." }, "always_asks_before_sending": { "type": "boolean", "description": "True when the step always goes to the broker first: `ask_before_sending: false` is refused." }, "default_ask_before_sending": { "type": "boolean", "description": "The value used when a step leaves `ask_before_sending` out." }, "params": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The key in `params`." }, "label": { "type": "string", "description": "The name of the setting on screen." }, "type": { "type": "string", "description": "The kind of value, for example `text`, `number`, `boolean`, `choice` or `list`." }, "required": { "type": "boolean", "description": "True when the step cannot be saved without it." }, "multiple": { "type": "boolean", "description": "True when the value is a list of choices." }, "default": { "nullable": true, "description": "The value used when the setting is left out. Null for none." }, "choices": { "nullable": true, "description": "The values to pick from, when they are fixed. Null when they come from `choices_from`.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to send." }, "label": { "type": "string", "description": "What the broker sees." } }, "required": [ "value", "label" ], "additionalProperties": false } }, "choices_from": { "nullable": true, "description": "Where the ids come from, when they are the brokerage's own records: `templates` and `smsTemplates` (`GET /v1/templates`), `tags` (`GET /v1/deal-tags`), `contactTags` (`GET /v1/contact-tags`), `stages` and `boards` (`GET /v1/pipelines`), `brokers` and `assignees` (`GET /v1/users`), `recipients` and `emailRecipients` (the catalog's `recipients`). Null when the values are fixed.", "type": "string" }, "shown_when": { "nullable": true, "description": "The setting applies only when another setting holds a value. Null when it always applies.", "type": "object", "properties": { "key": { "type": "string", "description": "The other setting." }, "equals": { "type": "string", "description": "The value that setting must hold." } }, "required": [ "key", "equals" ], "additionalProperties": false }, "help": { "nullable": true, "description": "More about the setting.", "type": "string" } }, "required": [ "key", "label", "type", "required", "multiple", "default", "choices", "choices_from", "shown_when", "help" ], "additionalProperties": false }, "description": "The settings the step takes in `params`." } }, "required": [ "kind", "label", "description", "group", "reaches_client", "always_asks_before_sending", "default_ask_before_sending", "params" ], "additionalProperties": false }, "description": "Every kind of step. A step that writes its own words to a client is not listed: save the words as a template and use the `email` or `sms` step." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to send." }, "label": { "type": "string", "description": "What the broker sees." } }, "required": [ "value", "label" ], "additionalProperties": false }, "description": "Who a message step can go to, in `toRecipients`, `ccRecipients` and `bccRecipients` (or the older `recipient`). On a trigger that runs on a deal, an email step can also name a role on the deal: `deal-role:@underwriter`, `deal-role:@submitting`, or `deal-role:` and a role your team added, for example `deal-role:Closing Officer`. The email goes to the teammate who holds that role on the deal." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The value of `field` in a check." }, "label": { "type": "string", "description": "The name of the field on screen." }, "type": { "type": "string", "description": "The kind of value, for example `text`, `money`, `date` or `choice`." }, "subjects": { "type": "array", "items": { "type": "string", "enum": [ "deal", "contact", "lead" ] }, "description": "The subjects the field can be checked on." }, "choices": { "nullable": true, "description": "The values to compare with, when they are fixed.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to send." }, "label": { "type": "string", "description": "What the broker sees." } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "key", "label", "type", "subjects", "choices" ], "additionalProperties": false }, "description": "The fields a check in `filters` or `only_if` can compare, including the brokerage's custom fields." }, "condition_ops": { "type": "array", "items": { "type": "string" }, "description": "The operators a check can use in `op`, for example `eq` or `gte`." }, "graph_nodes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "The value of `kind` on a graph node." }, "description": { "type": "string", "description": "What the node does, and the keys it takes." } }, "required": [ "kind", "description" ], "additionalProperties": false }, "description": "The node kinds a `graph` can hold. Edges join nodes by `from` and `to`, and the two edges out of a fork carry `branch`: `true` or `false`." } }, "required": [ "triggers", "steps", "recipients", "fields", "condition_ops", "graph_nodes" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations": { "get": { "operationId": "listAutomations", "summary": "List automations", "description": "The Pulse automations on the broker's board, each with its steps in order. A step with `ask_before_sending` set files a draft for the broker to review instead of sending.", "tags": [ "Automations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only automations started by this event, for example `stage.transitioned`." }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Send `true` for automations that run, or `false` for those that are off." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` is not a timestamp, or `enabled` is not `true` or `false` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAutomation", "summary": "Create an automation", "description": "Builds an automation from any event and any steps in the catalog, through the same checks as the app's builder. Send `steps` for a list, or `graph` for branches and waits. The automation is saved OFF. Turn it on with `POST /automations/{id}/turn-on`. A step that reaches a client asks before sending unless you set `ask_before_sending` to false. A step that writes its own words to a client is refused: save the words as a template and send the template.", "tags": [ "Automations" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name the broker sees." }, "description": { "description": "What the automation is for.", "nullable": true, "type": "string", "maxLength": 2000 }, "type": { "description": "The event that starts it: a trigger `type` from `GET /v1/automations/catalog`. The default is `stage.transitioned`. With a `graph`, the graph's trigger node names the type.", "type": "string" }, "config": { "description": "The settings of the event, as the catalog lists them for the type. For example `{ \"stageId\": \"...\" }` on `stage.transitioned`, or `{ \"statuses\": [\"approved\"] }` on `deal.status_changed`.", "type": "object", "additionalProperties": {} }, "stage_id": { "description": "A short form of `config.stageId` on `stage.transitioned`: the stage that starts it, from `GET /v1/pipelines`. Null or absent starts it on each stage change.", "nullable": true, "type": "string" }, "filters": { "description": "Checks a deal or contact must pass before it starts. A group: `{ \"match\": \"all\", \"rules\": [{ \"field\": \"deal.loanAmount\", \"op\": \"gte\", \"value\": 500000 }] }`. The catalog lists the fields and the operators.", "type": "object", "additionalProperties": {} }, "repeat_policy": { "description": "`once_per_subject` runs one time for each deal or contact. The default depends on the type.", "type": "string", "enum": [ "once_per_subject", "every_occurrence" ] }, "anchor_offset_days": { "description": "On a type that starts from a date: the days from that date that it starts. A negative number is before.", "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "canvas_id": { "description": "The canvas group to file it under. Null is no group.", "nullable": true, "type": "string" }, "steps": { "description": "The steps, in the order they run. Send `steps` or `graph`.", "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "description": "What the step does: a step `kind` from `GET /v1/automations/catalog`, for example `email`, `sms`, `task`, `tag` or `set_stage`. Send `kind` or `channel`.", "type": "string" }, "channel": { "description": "The older form of `kind` for a message step.", "type": "string", "enum": [ "email", "sms" ] }, "template_id": { "description": "The template the step uses, from `GET /v1/templates`. An `email` step needs an email template, and an `sms` step needs an SMS template. The same as `params.templateId`.", "type": "string" }, "params": { "description": "The settings of the step, as the catalog lists them for its `kind`. For example, on an `email` step `toRecipients` is who it goes to: `[\"primary_applicant\"]` (the default), or `[\"primary_applicant\", \"partner:realtor\"]` for the client and the realtor.", "type": "object", "additionalProperties": {} }, "delay_days": { "description": "Days after the automation starts before the step runs. The default is 0. List the steps in the order they run: a step cannot have a smaller delay than the step before it.", "type": "number", "minimum": 0, "maximum": 3650 }, "send_at_time": { "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "`HH:MM`, 24-hour. After its delay, the step waits for this time of day in the client's time zone." }, "ask_before_sending": { "description": "True files the step as a draft or an approval for the broker instead of doing it. The default is the catalog's `default_ask_before_sending` for the kind, which is true for every step that reaches a client.", "type": "boolean" }, "only_if": { "description": "More checks the deal or contact must pass when this step runs, in the same shape as `filters`.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false } }, "graph": { "description": "A drawing with branches, waits or repeats, in the shape `GET /v1/automations/{id}` returns. Send `steps` or `graph`, not both.", "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The definition cannot be saved. `details.fieldErrors` names each field at fault, for example `steps.1.params.templateId`, and says how to fix it: an unknown type or step kind (VALIDATION_ERROR, INVALID_STEP), steps out of order (INVALID_STEP), a bad setting of the event (INVALID_TRIGGER_CONFIG), a check on a field the event cannot read (INVALID_TRIGGER_FILTERS), a graph that cannot compile (INVALID_GRAPH), or a template with a merge field this event cannot fill (TEMPLATE_SUBJECT_MISMATCH).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "A template, stage, tag or other record the automation names is not in this brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/{id}": { "get": { "operationId": "getAutomation", "summary": "Retrieve an automation", "description": "One automation: the event that starts it, its checks, its steps in order, and its `graph` if it has one.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateAutomation", "summary": "Change an automation", "description": "Send only what you change. `steps` or `graph` replaces every step. A change to what the automation does (its event settings, checks, or steps) turns it OFF, A change to only `name`, `description`, or `canvas_id` leaves it on or off as it was.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name the broker sees." }, "description": { "description": "What the automation is for.", "nullable": true, "type": "string", "maxLength": 2000 }, "config": { "description": "The settings of the event, as the catalog lists them for the type. For example `{ \"stageId\": \"...\" }` on `stage.transitioned`, or `{ \"statuses\": [\"approved\"] }` on `deal.status_changed`.", "type": "object", "additionalProperties": {} }, "stage_id": { "description": "A short form of `config.stageId` on `stage.transitioned`: the stage that starts it, from `GET /v1/pipelines`. Null or absent starts it on each stage change.", "nullable": true, "type": "string" }, "filters": { "description": "Checks a deal or contact must pass before it starts. A group: `{ \"match\": \"all\", \"rules\": [{ \"field\": \"deal.loanAmount\", \"op\": \"gte\", \"value\": 500000 }] }`. The catalog lists the fields and the operators.", "type": "object", "additionalProperties": {} }, "repeat_policy": { "description": "`once_per_subject` runs one time for each deal or contact. The default depends on the type.", "type": "string", "enum": [ "once_per_subject", "every_occurrence" ] }, "anchor_offset_days": { "description": "On a type that starts from a date: the days from that date that it starts. A negative number is before.", "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "canvas_id": { "description": "The canvas group to file it under. Null is no group.", "nullable": true, "type": "string" }, "steps": { "description": "The steps, in the order they run. Send `steps` or `graph`.", "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "description": "What the step does: a step `kind` from `GET /v1/automations/catalog`, for example `email`, `sms`, `task`, `tag` or `set_stage`. Send `kind` or `channel`.", "type": "string" }, "channel": { "description": "The older form of `kind` for a message step.", "type": "string", "enum": [ "email", "sms" ] }, "template_id": { "description": "The template the step uses, from `GET /v1/templates`. An `email` step needs an email template, and an `sms` step needs an SMS template. The same as `params.templateId`.", "type": "string" }, "params": { "description": "The settings of the step, as the catalog lists them for its `kind`. For example, on an `email` step `toRecipients` is who it goes to: `[\"primary_applicant\"]` (the default), or `[\"primary_applicant\", \"partner:realtor\"]` for the client and the realtor.", "type": "object", "additionalProperties": {} }, "delay_days": { "description": "Days after the automation starts before the step runs. The default is 0. List the steps in the order they run: a step cannot have a smaller delay than the step before it.", "type": "number", "minimum": 0, "maximum": 3650 }, "send_at_time": { "nullable": true, "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "`HH:MM`, 24-hour. After its delay, the step waits for this time of day in the client's time zone." }, "ask_before_sending": { "description": "True files the step as a draft or an approval for the broker instead of doing it. The default is the catalog's `default_ask_before_sending` for the kind, which is true for every step that reaches a client.", "type": "boolean" }, "only_if": { "description": "More checks the deal or contact must pass when this step runs, in the same shape as `filters`.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false } }, "graph": { "description": "A drawing with branches, waits or repeats, in the shape `GET /v1/automations/{id}` returns. Send `steps` or `graph`, not both.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The change cannot be saved. `details.fieldErrors` names each field at fault and says how to fix it, as for a create. `type` cannot change (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The automation has a `graph`: send a changed `graph`, not `steps` (DRAWN_ON_CANVAS).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteAutomation", "summary": "Delete an automation", "description": "Turns the automation off and removes it from the board. Steps still waiting in its runs do not run. Its runs stay readable through `GET /automation-runs`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/{id}/duplicate": { "post": { "operationId": "duplicateAutomation", "summary": "Duplicate an automation", "description": "Makes a copy named ` copy` with the same event, checks and steps. The copy is saved OFF.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/{id}/turn-on": { "post": { "operationId": "turnOnAutomation", "summary": "Turn an automation on", "description": "Turns the automation on now, the same as its switch in BrokerPlus. The response is `200` with the automation. When the automation can message clients (`can_message_clients: true`), its steps can reach clients from now on, and a key with the `no_sending` limit is refused. An automation that is already on answers `200` with no change.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN), the key has the `no_sending` limit (KEY_LIMITED), or the broker may not send to clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/{id}/turn-off": { "post": { "operationId": "turnOffAutomation", "summary": "Turn an automation off", "description": "Turns the automation off now. Steps still waiting in its runs do not run. An automation that is already off answers with no change.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation", "description": "The type of this record. Always `automation`.", "type": "string", "enum": [ "automation" ] }, "id": { "type": "string", "description": "Stable identifier for the automation." }, "name": { "type": "string", "description": "The name the broker gave it." }, "description": { "nullable": true, "description": "What the automation is for.", "type": "string" }, "type": { "type": "string", "description": "The event that starts it, for example `stage.transitioned` (a deal moves into a stage). `GET /v1/automations/catalog` lists every type." }, "type_label": { "type": "string", "description": "The name of that event on screen, for example `Deal Moved into a Stage`." }, "config": { "type": "object", "additionalProperties": {}, "description": "The settings of the event. On `stage.transitioned`, `stageId` is the stage it waits for, and no `stageId` means any stage. The catalog lists the settings of each type." }, "filters": { "type": "object", "additionalProperties": {}, "description": "The checks a deal or contact must pass before the automation starts." }, "enabled": { "type": "boolean", "description": "True when it runs. `POST /v1/automations/{id}/turn-on` turns it on. When it can message clients, a key with the `no_sending` limit cannot turn it on." }, "can_message_clients": { "type": "boolean", "description": "True when a step can reach a client, for example an email or a text. A key with the `no_sending` limit cannot turn such an automation on." }, "repeat_policy": { "type": "string", "enum": [ "once_per_subject", "every_occurrence" ], "description": "`once_per_subject` runs one time for each deal or contact. `every_occurrence` runs each time the event occurs." }, "team_id": { "nullable": true, "description": "The broker team that owns it.", "type": "string" }, "canvas_id": { "nullable": true, "description": "The group it is filed under on the canvas. Null when it has no group.", "type": "string" }, "canvas_name": { "nullable": true, "description": "The name of that group.", "type": "string" }, "sort_order": { "nullable": true, "description": "Where the broker put it in its group on the canvas, ascending. Null when nobody has ordered the group: then the newest comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "anchor_offset_days": { "nullable": true, "description": "On an automation that starts from a date, such as a birthday or a maturity date: the days from that date that it starts. A negative number is before the date. Null on other types.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "drawn_on_canvas": { "type": "boolean", "description": "True when it has a `graph`. To change its steps, send a changed `graph`, not `steps`." }, "graph": { "nullable": true, "description": "The drawing, when the broker drew it on the canvas or you sent one: `{ version: 1, nodes, edges }`, with branches, waits and repeats. Null for a plain list of steps. The steps are compiled from it. The catalog's `graph_nodes` lists each node kind.", "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_step", "description": "The type of this record. Always `automation_step`.", "type": "string", "enum": [ "automation_step" ] }, "id": { "type": "string", "description": "Stable identifier for the step." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the step runs in the automation, from 0." }, "kind": { "type": "string", "description": "What the step does, for example `email`, `sms`, `task` or `set_stage`. `GET /v1/automations/catalog` lists every kind and its settings. Treat a kind that is not in the catalog as read-only." }, "label": { "type": "string", "description": "The name of the step on screen, for example `Send an email`." }, "delay_days": { "type": "number", "description": "Days after the automation starts before the step runs. Fractions are permitted, for example `0.5`." }, "send_at_time": { "nullable": true, "description": "The time of day the step waits for. Null sends when the delay ends.", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "ask_before_sending": { "type": "boolean", "description": "True when the step files a draft for the broker to review instead of sending it. False sends it with no review." }, "template_id": { "nullable": true, "description": "The template the step uses. Null when the step uses no template.", "type": "string" }, "template_name": { "nullable": true, "description": "The name of that template.", "type": "string" }, "params": { "type": "object", "additionalProperties": {}, "description": "The settings of the step, for example who it goes to. The keys change with `kind`." }, "only_if": { "type": "object", "additionalProperties": {}, "description": "More checks the deal or contact must pass when the step runs. An empty group always passes." }, "created_at": { "type": "string", "description": "When the step was added." }, "updated_at": { "type": "string", "description": "Last change to the step." } }, "required": [ "object", "id", "position", "kind", "label", "delay_days", "send_at_time", "ask_before_sending", "template_id", "template_name", "params", "only_if", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The steps, in the order they run." }, "created_at": { "type": "string", "description": "When it was created." }, "updated_at": { "type": "string", "description": "Last change. Poll with `updated_since` to sync incrementally." } }, "required": [ "object", "id", "name", "description", "type", "type_label", "config", "filters", "enabled", "can_message_clients", "repeat_policy", "team_id", "canvas_id", "canvas_name", "sort_order", "anchor_offset_days", "drawn_on_canvas", "graph", "steps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/canvases": { "get": { "operationId": "listAutomationCanvases", "summary": "List canvas groups", "description": "The groups the automations are filed under on the automation canvas, in the order BrokerPlus shows them: the highest `position` first. Only the groups of the broker's own teams are listed. An automation with no group has `canvas_id` null.", "tags": [ "Automations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_canvas", "description": "The type of this record. Always `automation_canvas`.", "type": "string", "enum": [ "automation_canvas" ] }, "id": { "type": "string", "description": "Stable identifier for the canvas group." }, "team_id": { "type": "string", "description": "The broker team that owns the group. Only its members see it." }, "name": { "type": "string", "description": "The group's name." }, "description": { "nullable": true, "description": "What the group is for. Null when it has none.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the group sits in the list. The highest is at the top, the same order as BrokerPlus." }, "automation_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many automations are filed in the group. Read them with `GET /v1/automations` and `canvas_id`." }, "enabled_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them are on. Equal to `automation_count` means the group is on, `0` means it is off, and any other value means some are on." }, "created_at": { "type": "string", "description": "When the group was made." }, "updated_at": { "type": "string", "description": "When its name, description or position last changed." } }, "required": [ "object", "id", "team_id", "name", "description", "position", "automation_count", "enabled_count", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAutomationCanvas", "summary": "Create a canvas group", "description": "Makes a group on the automation canvas, on the broker's active team, the same as New group in BrokerPlus. File an automation in it with `canvas_id` on `POST /v1/automations` or `PATCH /v1/automations/{id}`.", "tags": [ "Automations" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The group's name, 1 to 120 characters." }, "description": { "description": "What the group is for, up to 500 characters. Null clears it.", "nullable": true, "type": "string", "maxLength": 500 }, "position": { "description": "Where the group sits, 0 to 1000; the highest is at the top. Leave it out to put a new group on top.", "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_canvas", "description": "The type of this record. Always `automation_canvas`.", "type": "string", "enum": [ "automation_canvas" ] }, "id": { "type": "string", "description": "Stable identifier for the canvas group." }, "team_id": { "type": "string", "description": "The broker team that owns the group. Only its members see it." }, "name": { "type": "string", "description": "The group's name." }, "description": { "nullable": true, "description": "What the group is for. Null when it has none.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the group sits in the list. The highest is at the top, the same order as BrokerPlus." }, "automation_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many automations are filed in the group. Read them with `GET /v1/automations` and `canvas_id`." }, "enabled_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them are on. Equal to `automation_count` means the group is on, `0` means it is off, and any other value means some are on." }, "created_at": { "type": "string", "description": "When the group was made." }, "updated_at": { "type": "string", "description": "When its name, description or position last changed." } }, "required": [ "object", "id", "team_id", "name", "description", "position", "automation_count", "enabled_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The broker is on no team, or is working in a team they only read (NO_TEAM, READ_ONLY_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/canvases/{id}": { "get": { "operationId": "getAutomationCanvas", "summary": "Retrieve a canvas group", "description": "One canvas group, with how many automations it holds and how many of them are on.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_canvas", "description": "The type of this record. Always `automation_canvas`.", "type": "string", "enum": [ "automation_canvas" ] }, "id": { "type": "string", "description": "Stable identifier for the canvas group." }, "team_id": { "type": "string", "description": "The broker team that owns the group. Only its members see it." }, "name": { "type": "string", "description": "The group's name." }, "description": { "nullable": true, "description": "What the group is for. Null when it has none.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the group sits in the list. The highest is at the top, the same order as BrokerPlus." }, "automation_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many automations are filed in the group. Read them with `GET /v1/automations` and `canvas_id`." }, "enabled_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them are on. Equal to `automation_count` means the group is on, `0` means it is off, and any other value means some are on." }, "created_at": { "type": "string", "description": "When the group was made." }, "updated_at": { "type": "string", "description": "When its name, description or position last changed." } }, "required": [ "object", "id", "team_id", "name", "description", "position", "automation_count", "enabled_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateAutomationCanvas", "summary": "Update a canvas group", "description": "Renames, describes or moves a group. It does not change its automations or turn anything on or off.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The group's name, 1 to 120 characters." }, "description": { "description": "What the group is for, up to 500 characters. Null clears it.", "nullable": true, "type": "string", "maxLength": 500 }, "position": { "description": "Where the group sits, 0 to 1000; the highest is at the top. Leave it out to put a new group on top.", "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_canvas", "description": "The type of this record. Always `automation_canvas`.", "type": "string", "enum": [ "automation_canvas" ] }, "id": { "type": "string", "description": "Stable identifier for the canvas group." }, "team_id": { "type": "string", "description": "The broker team that owns the group. Only its members see it." }, "name": { "type": "string", "description": "The group's name." }, "description": { "nullable": true, "description": "What the group is for. Null when it has none.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the group sits in the list. The highest is at the top, the same order as BrokerPlus." }, "automation_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many automations are filed in the group. Read them with `GET /v1/automations` and `canvas_id`." }, "enabled_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of them are on. Equal to `automation_count` means the group is on, `0` means it is off, and any other value means some are on." }, "created_at": { "type": "string", "description": "When the group was made." }, "updated_at": { "type": "string", "description": "When its name, description or position last changed." } }, "required": [ "object", "id", "team_id", "name", "description", "position", "automation_count", "enabled_count", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteAutomationCanvas", "summary": "Delete a canvas group", "description": "Deletes the group and every automation in it, the same as Delete group in BrokerPlus. The automations are turned off first, and their run history stays.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/canvases/{id}/turn-on": { "post": { "operationId": "turnOnAutomationCanvas", "summary": "Turn a canvas group on", "description": "Turns on every automation in the group now, the same as the group's switch in BrokerPlus. `results` has a line for each automation. If an automation that is off can message clients and your key has the `no_sending` limit, nothing changes.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_canvas_switch", "description": "The type of this record. Always `automation_canvas_switch`.", "type": "string", "enum": [ "automation_canvas_switch" ] }, "id": { "type": "string", "description": "The canvas group." }, "results": { "type": "array", "items": { "type": "object", "properties": { "automation_id": { "type": "string", "description": "The automation." }, "name": { "type": "string", "description": "The automation's name." }, "result": { "type": "string", "enum": [ "on", "off", "unchanged" ], "description": "`on` or `off`: it changed now. `unchanged`: it was already that way." } }, "required": [ "automation_id", "name", "result" ], "additionalProperties": false }, "description": "One line for each automation in the group." } }, "required": [ "object", "id", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN), your key has the `no_sending` limit (KEY_LIMITED), or the broker may not send to clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/canvases/{id}/turn-off": { "post": { "operationId": "turnOffAutomationCanvas", "summary": "Turn a canvas group off", "description": "Turns off every automation in the group now, in one change.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "automation_canvas_switch", "description": "The type of this record. Always `automation_canvas_switch`.", "type": "string", "enum": [ "automation_canvas_switch" ] }, "id": { "type": "string", "description": "The canvas group." }, "results": { "type": "array", "items": { "type": "object", "properties": { "automation_id": { "type": "string", "description": "The automation." }, "name": { "type": "string", "description": "The automation's name." }, "result": { "type": "string", "enum": [ "on", "off", "unchanged" ], "description": "`on` or `off`: it changed now. `unchanged`: it was already that way." } }, "required": [ "automation_id", "name", "result" ], "additionalProperties": false }, "description": "One line for each automation in the group." } }, "required": [ "object", "id", "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/stops": { "get": { "operationId": "listAutomationStops", "summary": "List automation stops", "description": "The clients that automations do not message, newest first: Stop automated outreach on a contact in BrokerPlus, and the block list in Pulse. A stage that stops automated messages, and a client tag automation, can also make or join a stop.", "tags": [ "Automations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only stops made at or after it, in `created_at` order and then `id` order, oldest first. A stop never changes: it is made, and later lifted. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `created_at` and `id` of the last row you read. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the stops on this client." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the stops for this deal." }, { "name": "automation_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only the stops that hold back this kind of automation, including the stops on every automation." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_stop", "description": "The type of this record. Always `automation_stop`.", "type": "string", "enum": [ "automation_stop" ] }, "id": { "type": "string", "description": "Stable identifier for the stop." }, "contact_id": { "type": "string", "description": "The client that automations do not message." }, "contact_name": { "nullable": true, "description": "The client's name, for display. Null when it has none.", "type": "string" }, "deal_id": { "nullable": true, "description": "The one deal the stop covers. Null when it covers every deal of the client.", "type": "string" }, "automation_type": { "nullable": true, "description": "The kind of automation the stop holds back, a `type` from `GET /v1/automations/catalog`. Null when it holds back every automation.", "type": "string" }, "held_by_stage": { "type": "boolean", "description": "True when a deal of the client is in a stage that stops automated messages. The stop then ends by itself when no deal of theirs is in such a stage." }, "held_by_tag_ids": { "type": "array", "items": { "type": "string" }, "description": "The client tags whose automations made or joined this stop. It ends by itself when the client has none of them and no stage holds it." }, "created_by_user_id": { "nullable": true, "description": "Who stopped it. Null when a stage or a tag did.", "type": "string" }, "created_at": { "type": "string", "description": "When it was stopped." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "automation_type", "held_by_stage", "held_by_tag_ids", "created_by_user_id", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createAutomationStop", "summary": "Stop automations messaging a client", "description": "Stops automations from messaging a client, the same as Stop automated outreach in BrokerPlus. Without `deal_id` and `automation_types` it stops every automation for every deal of the client, and takes them off the equity reports they get a copy of as a realtor. This only stops messages, so it happens now. A second call with the same body changes nothing. Lift a stop with `POST /automations/stops/{id}/lift`.", "tags": [ "Automations" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The client to stop messaging. Find it with `GET /v1/contacts`." }, "deal_id": { "description": "Stop only for this deal of the client. Leave it out or send null for every deal.", "nullable": true, "type": "string", "minLength": 1 }, "automation_types": { "description": "Stop only these kinds of automation, as `type` values from `GET /v1/automations/catalog`. Leave it out or send null for every automation.", "nullable": true, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The client." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "automation_stop", "description": "The type of this record. Always `automation_stop`.", "type": "string", "enum": [ "automation_stop" ] }, "id": { "type": "string", "description": "Stable identifier for the stop." }, "contact_id": { "type": "string", "description": "The client that automations do not message." }, "contact_name": { "nullable": true, "description": "The client's name, for display. Null when it has none.", "type": "string" }, "deal_id": { "nullable": true, "description": "The one deal the stop covers. Null when it covers every deal of the client.", "type": "string" }, "automation_type": { "nullable": true, "description": "The kind of automation the stop holds back, a `type` from `GET /v1/automations/catalog`. Null when it holds back every automation.", "type": "string" }, "held_by_stage": { "type": "boolean", "description": "True when a deal of the client is in a stage that stops automated messages. The stop then ends by itself when no deal of theirs is in such a stage." }, "held_by_tag_ids": { "type": "array", "items": { "type": "string" }, "description": "The client tags whose automations made or joined this stop. It ends by itself when the client has none of them and no stage holds it." }, "created_by_user_id": { "nullable": true, "description": "Who stopped it. Null when a stage or a tag did.", "type": "string" }, "created_at": { "type": "string", "description": "When it was stopped." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "automation_type", "held_by_stage", "held_by_tag_ids", "created_by_user_id", "created_at" ], "additionalProperties": false }, "description": "Every stop on the client now, newest first." } }, "required": [ "contact_id", "stops" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "An `automation_types` value is not a type from `GET /automations/catalog` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact or the deal does not exist, or the broker cannot change the contact (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/automations/stops/{id}/lift": { "post": { "operationId": "liftAutomationStop", "summary": "Lift an automation stop", "description": "Lifts the stop now, so automations can message the client again. The response is `200`, and the stop is gone. A stop that a stage holds (`held_by_stage`) comes back while the client's deal stays in that stage. A key with the `no_sending` limit is refused.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change automations (AUTOMATION_MANAGE_FORBIDDEN), your key has the `no_sending` limit (KEY_LIMITED), or the broker may not send to clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The stop does not exist, or the broker cannot change its client (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another call lifted the stop first (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports": { "get": { "operationId": "listEquityReports", "summary": "List equity reports", "description": "The monthly reports sent to past clients, newest first. The figures are the snapshot the client was sent, not today's numbers; read today's numbers from `GET /v1/opportunities`. `cta_clicked_at` is the client asking for a call.", "tags": [ "Equity reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only reports for this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only reports about this client: reports built from a deal the contact is on." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "viewed", "interacted" ] }, "description": "Return only reports in this state." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "equity_report", "description": "The type of this record. Always `equity_report`.", "type": "string", "enum": [ "equity_report" ] }, "id": { "type": "string", "description": "Stable identifier for the report." }, "deal_id": { "type": "string", "description": "The deal it was built from." }, "contact_id": { "nullable": true, "description": "The client the report is about: the primary applicant on the deal. Null when the deal has none.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client's name, for display. Null when you cannot read that contact.", "type": "string" }, "month": { "type": "string", "description": "The month the report covers, e.g. `March 2026`." }, "type": { "type": "string", "enum": [ "property", "debt" ], "description": "`property` is the equity report. `debt` is a consolidation report the broker composed." }, "status": { "type": "string", "description": "`sent`, `viewed`, or `interacted`. It says how far the client got." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the report reached the client: `email` or `sms`." }, "address": { "nullable": true, "description": "The property, as it read on the report.", "type": "string" }, "property_value": { "nullable": true, "description": "Property value on the report, in dollars.", "type": "number" }, "mortgage_balance": { "nullable": true, "description": "Mortgage balance on the report, in dollars.", "type": "number" }, "equity": { "nullable": true, "description": "Equity on the report, in dollars.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan-to-value on the report, as a percent. `65` means 65%.", "type": "number" }, "heloc_max": { "nullable": true, "description": "The largest line of credit the report showed, in dollars.", "type": "number" }, "viewed_at": { "nullable": true, "description": "When the client first opened the report. Null when they have not.", "type": "string" }, "cta_clicked_at": { "nullable": true, "description": "When the client asked the broker to call. This is the signal worth acting on.", "type": "string" }, "expires_at": { "type": "string", "description": "When the client's link stops working." }, "created_at": { "type": "string", "description": "When the report was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "month", "type", "status", "channel", "address", "property_value", "mortgage_balance", "equity", "ltv", "heloc_max", "viewed_at", "cta_clicked_at", "expires_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/sends": { "get": { "operationId": "listEquityReportSends", "summary": "List equity report sends", "description": "Every time an equity report went out to a client, newest first, the same history as Outreach History in BrokerPlus. A report the client got twice is listed twice. To see whether the client opened it, read `GET /v1/equity-reports/interactions`.", "tags": [ "Equity reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only sends at or after it, in `sent_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `sent_at` and `id` of the last row you read. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only sends for this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only sends to this client." }, { "name": "report_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only sends of this report." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "sms" ] }, "description": "Return only sends on this channel." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "failed", "suppressed" ] }, "description": "Return only sends with this status." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "equity_report_send", "description": "The type of this record. Always `equity_report_send`.", "type": "string", "enum": [ "equity_report_send" ] }, "id": { "type": "string", "description": "Stable identifier for the send." }, "deal_id": { "type": "string", "description": "The deal the report was built from." }, "report_id": { "nullable": true, "description": "The report that went out. Read it with `GET /v1/equity-reports/{id}`. Null for an older send.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client the report went to. Null when no one person was named.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client's name, for display. Null when you cannot read that contact.", "type": "string" }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the report went out: `email` or `sms`." }, "status": { "type": "string", "description": "`sent`, `failed`, or `suppressed`. It says whether the report left BrokerPlus. To see whether the client opened it, read the report's `status`." }, "frequency": { "nullable": true, "description": "The cadence the report went out on, for example `monthly` or `quarterly`. Null for a one-off send. It stays as it was when sent, after the client's cadence changes.", "type": "string" }, "subject": { "nullable": true, "description": "The email subject line. Null for a text.", "type": "string" }, "month": { "type": "string", "description": "The month the report covers, e.g. `March 2026`." }, "sent_at": { "type": "string", "description": "When the report went out." } }, "required": [ "object", "id", "deal_id", "report_id", "contact_id", "contact_name", "channel", "status", "frequency", "subject", "month", "sent_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/interactions": { "get": { "operationId": "listEquityReportInteractions", "summary": "List equity report interactions", "description": "What clients did with their reports, newest first: opened the email, opened the report, asked for a call, or corrected a figure. A correction the client made is held for the broker to accept or refuse in BrokerPlus.", "tags": [ "Equity reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only interactions at or after it, in `created_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `created_at` and `id` of the last row you read. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only interactions with reports for this deal." }, { "name": "report_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only interactions with this report." }, { "name": "field", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email_open", "page_view", "cta_click", "propertyAddress", "propertyValue", "mortgageBalance" ] }, "description": "Return only this kind of interaction." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "equity_report_interaction", "description": "The type of this record. Always `equity_report_interaction`.", "type": "string", "enum": [ "equity_report_interaction" ] }, "id": { "type": "string", "description": "Stable identifier for the interaction." }, "report_id": { "type": "string", "description": "The report the client opened or changed." }, "deal_id": { "type": "string", "description": "The deal the report was built from." }, "field": { "type": "string", "description": "What the client did. `email_open` opened the email, `page_view` opened the report, `cta_click` asked the broker to call. `propertyAddress`, `propertyValue`, or `mortgageBalance` corrected that figure on the report." }, "old_value": { "nullable": true, "description": "For a correction: the figure before the client changed it. Else null.", "type": "string" }, "new_value": { "nullable": true, "description": "For a correction: the figure the client entered. Else null.", "type": "string" }, "recalculated_equity": { "nullable": true, "description": "For a correction: the equity the report showed after it, in dollars. Else null.", "type": "number" }, "recalculated_ltv": { "nullable": true, "description": "For a correction: the loan-to-value the report showed after it, as a percent. Else null.", "type": "number" }, "created_at": { "type": "string", "description": "When the client did it." } }, "required": [ "object", "id", "report_id", "deal_id", "field", "old_value", "new_value", "recalculated_equity", "recalculated_ltv", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-report-changes": { "get": { "operationId": "listEquityReportChanges", "summary": "List clients' equity report corrections", "description": "The corrections clients made to their equity reports: the property's address, its value, or the mortgage balance. A `pending` one waits for the broker, as on the report changes queue in BrokerPlus. Newest first, or oldest first with `updated_since`.", "tags": [ "Equity reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "applied", "rejected", "withdrawn" ] }, "description": "Only corrections in this state." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only corrections on this deal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "equity_report_change", "description": "The type of this record. Always `equity_report_change`.", "type": "string", "enum": [ "equity_report_change" ] }, "id": { "type": "string", "description": "Stable identifier for the change." }, "deal_id": { "type": "string", "description": "The deal the client's report is for." }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "report_id": { "nullable": true, "description": "The equity report the client corrected. Null when it is unknown.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client who sent the change, when their link names them. Null for the report's shared link, which every recipient opens.", "type": "string" }, "field": { "type": "string", "enum": [ "propertyAddress", "propertyValue", "mortgageBalance" ], "description": "What the client corrected: the property's address, its value, or the mortgage balance." }, "old_value": { "nullable": true, "description": "What the report said before the client changed it.", "type": "string" }, "new_value": { "type": "string", "description": "What the client says it is. A value or balance is in dollars." }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected", "withdrawn" ], "description": "`pending` waits for the broker. `applied` is on the deal. `rejected` the broker declined. `withdrawn` the client took back before the broker answered." }, "held_reason": { "nullable": true, "description": "Why it waited for the broker: `awaiting_review` the brokerage reviews every change, `data_locked` the deal's client data is locked. Null when it went straight onto the deal.", "type": "string", "enum": [ "awaiting_review", "data_locked" ] }, "resolved_at": { "nullable": true, "description": "When it was applied, declined or withdrawn. Null while it waits.", "type": "string" }, "resolved_by_user_id": { "nullable": true, "description": "The broker who accepted or declined it. Null while it waits, or when nobody had to.", "type": "string" }, "created_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "deal_name", "report_id", "contact_id", "field", "old_value", "new_value", "status", "held_reason", "resolved_at", "resolved_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-report-changes/{id}": { "get": { "operationId": "getEquityReportChange", "summary": "Retrieve a client's equity report correction", "description": "One correction a client made to their equity report.", "tags": [ "Equity reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "equity_report_change", "description": "The type of this record. Always `equity_report_change`.", "type": "string", "enum": [ "equity_report_change" ] }, "id": { "type": "string", "description": "Stable identifier for the change." }, "deal_id": { "type": "string", "description": "The deal the client's report is for." }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "report_id": { "nullable": true, "description": "The equity report the client corrected. Null when it is unknown.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client who sent the change, when their link names them. Null for the report's shared link, which every recipient opens.", "type": "string" }, "field": { "type": "string", "enum": [ "propertyAddress", "propertyValue", "mortgageBalance" ], "description": "What the client corrected: the property's address, its value, or the mortgage balance." }, "old_value": { "nullable": true, "description": "What the report said before the client changed it.", "type": "string" }, "new_value": { "type": "string", "description": "What the client says it is. A value or balance is in dollars." }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected", "withdrawn" ], "description": "`pending` waits for the broker. `applied` is on the deal. `rejected` the broker declined. `withdrawn` the client took back before the broker answered." }, "held_reason": { "nullable": true, "description": "Why it waited for the broker: `awaiting_review` the brokerage reviews every change, `data_locked` the deal's client data is locked. Null when it went straight onto the deal.", "type": "string", "enum": [ "awaiting_review", "data_locked" ] }, "resolved_at": { "nullable": true, "description": "When it was applied, declined or withdrawn. Null while it waits.", "type": "string" }, "resolved_by_user_id": { "nullable": true, "description": "The broker who accepted or declined it. Null while it waits, or when nobody had to.", "type": "string" }, "created_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "deal_name", "report_id", "contact_id", "field", "old_value", "new_value", "status", "held_reason", "resolved_at", "resolved_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-report-changes/{id}/accept": { "post": { "operationId": "acceptEquityReportChange", "summary": "Accept a client's equity report correction", "description": "Writes the client's figure onto the deal, and the correction becomes `applied`. Nothing is sent to the client; their next report shows the new figure.", "tags": [ "Equity reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "equity_report_change", "description": "The type of this record. Always `equity_report_change`.", "type": "string", "enum": [ "equity_report_change" ] }, "id": { "type": "string", "description": "Stable identifier for the change." }, "deal_id": { "type": "string", "description": "The deal the client's report is for." }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "report_id": { "nullable": true, "description": "The equity report the client corrected. Null when it is unknown.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client who sent the change, when their link names them. Null for the report's shared link, which every recipient opens.", "type": "string" }, "field": { "type": "string", "enum": [ "propertyAddress", "propertyValue", "mortgageBalance" ], "description": "What the client corrected: the property's address, its value, or the mortgage balance." }, "old_value": { "nullable": true, "description": "What the report said before the client changed it.", "type": "string" }, "new_value": { "type": "string", "description": "What the client says it is. A value or balance is in dollars." }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected", "withdrawn" ], "description": "`pending` waits for the broker. `applied` is on the deal. `rejected` the broker declined. `withdrawn` the client took back before the broker answered." }, "held_reason": { "nullable": true, "description": "Why it waited for the broker: `awaiting_review` the brokerage reviews every change, `data_locked` the deal's client data is locked. Null when it went straight onto the deal.", "type": "string", "enum": [ "awaiting_review", "data_locked" ] }, "resolved_at": { "nullable": true, "description": "When it was applied, declined or withdrawn. Null while it waits.", "type": "string" }, "resolved_by_user_id": { "nullable": true, "description": "The broker who accepted or declined it. Null while it waits, or when nobody had to.", "type": "string" }, "created_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "deal_name", "report_id", "contact_id", "field", "old_value", "new_value", "status", "held_reason", "resolved_at", "resolved_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The deal's client data is locked to its own broker (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The correction does not exist or no longer waits for the broker (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Someone already answered it (ALREADY_RESOLVED), or the deal cannot take the figure (CANNOT_APPLY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-report-changes/{id}/decline": { "post": { "operationId": "declineEquityReportChange", "summary": "Decline a client's equity report correction", "description": "Keeps the deal's figure, and the correction becomes `rejected`. A declined property value is taken back off the client's report. Nothing is sent to the client.", "tags": [ "Equity reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "equity_report_change", "description": "The type of this record. Always `equity_report_change`.", "type": "string", "enum": [ "equity_report_change" ] }, "id": { "type": "string", "description": "Stable identifier for the change." }, "deal_id": { "type": "string", "description": "The deal the client's report is for." }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "report_id": { "nullable": true, "description": "The equity report the client corrected. Null when it is unknown.", "type": "string" }, "contact_id": { "nullable": true, "description": "The client who sent the change, when their link names them. Null for the report's shared link, which every recipient opens.", "type": "string" }, "field": { "type": "string", "enum": [ "propertyAddress", "propertyValue", "mortgageBalance" ], "description": "What the client corrected: the property's address, its value, or the mortgage balance." }, "old_value": { "nullable": true, "description": "What the report said before the client changed it.", "type": "string" }, "new_value": { "type": "string", "description": "What the client says it is. A value or balance is in dollars." }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected", "withdrawn" ], "description": "`pending` waits for the broker. `applied` is on the deal. `rejected` the broker declined. `withdrawn` the client took back before the broker answered." }, "held_reason": { "nullable": true, "description": "Why it waited for the broker: `awaiting_review` the brokerage reviews every change, `data_locked` the deal's client data is locked. Null when it went straight onto the deal.", "type": "string", "enum": [ "awaiting_review", "data_locked" ] }, "resolved_at": { "nullable": true, "description": "When it was applied, declined or withdrawn. Null while it waits.", "type": "string" }, "resolved_by_user_id": { "nullable": true, "description": "The broker who accepted or declined it. Null while it waits, or when nobody had to.", "type": "string" }, "created_at": { "type": "string", "description": "When the client sent it." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "deal_id", "deal_name", "report_id", "contact_id", "field", "old_value", "new_value", "status", "held_reason", "resolved_at", "resolved_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The correction does not exist or no longer waits for the broker (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Someone already answered it (ALREADY_RESOLVED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-signals": { "get": { "operationId": "listPulseSignals", "summary": "List retention signals", "description": "The reasons BrokerPlus raised to reach a past client now: their loan-to-value fell below the brokerage's line, or a date of theirs is coming up. Newest first, or oldest first with `updated_since`.", "tags": [ "Retention signals" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ] }, "description": "Only signals of this kind." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "open", "drafted", "sent", "actioned", "dismissed" ] }, "description": "Only signals in this state." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only signals about this client." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only signals about this deal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pulse_signal", "description": "The type of this record. Always `pulse_signal`.", "type": "string", "enum": [ "pulse_signal" ] }, "id": { "type": "string", "description": "Stable identifier for the signal." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "Why to reach the client: `equity` their loan-to-value fell below the brokerage's line, or the date of their `mortgage_anniversary`, `birthday`, or the `new_year`." }, "status": { "type": "string", "enum": [ "scheduled", "open", "drafted", "sent", "actioned", "dismissed" ], "description": "`scheduled` waits for its date. `drafted` has a draft for the broker to review. `open` needs the broker and has no draft. `sent` the message went out. `actioned` the broker handled it outside BrokerPlus. `dismissed` the broker set it aside." }, "contact_id": { "type": "string", "description": "The client the signal is about." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null for a date signal on a contact.", "type": "string" }, "broker_id": { "nullable": true, "description": "The broker who owns it, when it is not the trigger's or the deal's broker. Null otherwise.", "type": "string" }, "trigger_id": { "nullable": true, "description": "The date trigger that made it. Null for an equity signal.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When it is due. Null for an equity signal, which is due at once.", "type": "string" }, "sent_at": { "nullable": true, "description": "When its message went out. Null until then.", "type": "string" }, "draft_id": { "nullable": true, "description": "The draft written for it. Read it with `GET /v1/drafts/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the signal was raised." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "type", "status", "contact_id", "deal_id", "broker_id", "trigger_id", "scheduled_at", "sent_at", "draft_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-signals/{id}": { "get": { "operationId": "getPulseSignal", "summary": "Retrieve a retention signal", "description": "One retention signal.", "tags": [ "Retention signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_signal", "description": "The type of this record. Always `pulse_signal`.", "type": "string", "enum": [ "pulse_signal" ] }, "id": { "type": "string", "description": "Stable identifier for the signal." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "Why to reach the client: `equity` their loan-to-value fell below the brokerage's line, or the date of their `mortgage_anniversary`, `birthday`, or the `new_year`." }, "status": { "type": "string", "enum": [ "scheduled", "open", "drafted", "sent", "actioned", "dismissed" ], "description": "`scheduled` waits for its date. `drafted` has a draft for the broker to review. `open` needs the broker and has no draft. `sent` the message went out. `actioned` the broker handled it outside BrokerPlus. `dismissed` the broker set it aside." }, "contact_id": { "type": "string", "description": "The client the signal is about." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null for a date signal on a contact.", "type": "string" }, "broker_id": { "nullable": true, "description": "The broker who owns it, when it is not the trigger's or the deal's broker. Null otherwise.", "type": "string" }, "trigger_id": { "nullable": true, "description": "The date trigger that made it. Null for an equity signal.", "type": "string" }, "scheduled_at": { "nullable": true, "description": "When it is due. Null for an equity signal, which is due at once.", "type": "string" }, "sent_at": { "nullable": true, "description": "When its message went out. Null until then.", "type": "string" }, "draft_id": { "nullable": true, "description": "The draft written for it. Read it with `GET /v1/drafts/{id}`.", "type": "string" }, "created_at": { "type": "string", "description": "When the signal was raised." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "type", "status", "contact_id", "deal_id", "broker_id", "trigger_id", "scheduled_at", "sent_at", "draft_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-triggers": { "get": { "operationId": "listPulseTriggers", "summary": "List the broker's date triggers", "description": "The dates the broker reaches clients on: their mortgage anniversary, their birthday, and the new year, with the message for each and whether it goes out on its own.", "tags": [ "Retention signals" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createPulseTrigger", "summary": "Set up a date trigger", "description": "Sets up one of the broker's date triggers, switched off. Turn it on with `POST /v1/pulse-triggers/{id}/turn-on`. The message is the BrokerPlus default for that date. Supports `Idempotency-Key`.", "tags": [ "Retention signals" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mortgage_anniversary", "birthday", "new_year" ], "description": "The date to watch. The broker has at most one trigger for each." }, "days_offset": { "type": "integer", "minimum": -90, "maximum": 90, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90. Defaults to 0, on the day." } }, "required": [ "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker already has a trigger for this date (DUPLICATE). `details.id` names it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-triggers/{id}": { "get": { "operationId": "getPulseTrigger", "summary": "Retrieve a date trigger", "description": "One of the broker's date triggers.", "tags": [ "Retention signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updatePulseTrigger", "summary": "Change when a date trigger acts", "description": "Moves the day a trigger acts, relative to the date. A trigger that is on stays on, and acts on the new day from its next date.", "tags": [ "Retention signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days_offset": { "type": "integer", "minimum": -90, "maximum": 90, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90. Defaults to 0, on the day." } }, "required": [ "days_offset" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-triggers/{id}/turn-on": { "post": { "operationId": "turnOnPulseTrigger", "summary": "Turn on a date trigger", "description": "Turns the trigger on. From then on BrokerPlus writes to each of the broker's clients on that date, and sends it on its own when `auto_send` is true. A trigger that is already on is answered as it stands. A key with the `no_sending` limit gets `403`. Supports `Idempotency-Key`.", "tags": [ "Retention signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker your key acts as may not send to clients from BrokerPlus (FORBIDDEN). A key with the `no_sending` limit is refused (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pulse-triggers/{id}/turn-off": { "post": { "operationId": "turnOffPulseTrigger", "summary": "Turn off a date trigger", "description": "Turns the trigger off, so it schedules nothing new. A message it already scheduled, up to a week ahead, still goes out: see it with `GET /v1/pulse-signals?status=scheduled`. A trigger that is already off is answered as it stands.", "tags": [ "Retention signals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pulse_trigger", "description": "The type of this record. Always `pulse_trigger`.", "type": "string", "enum": [ "pulse_trigger" ] }, "id": { "type": "string", "description": "Stable identifier for the trigger." }, "broker_id": { "type": "string", "description": "The broker whose trigger it is." }, "type": { "type": "string", "enum": [ "equity", "mortgage_anniversary", "birthday", "new_year" ], "description": "The date it watches: `mortgage_anniversary`, `birthday`, or `new_year`." }, "subject": { "nullable": true, "description": "The broker's own subject line. Null uses the BrokerPlus default.", "type": "string" }, "body": { "nullable": true, "description": "The broker's own message, with merge fields. Null uses the BrokerPlus default.", "type": "string" }, "is_active": { "type": "boolean", "description": "True while the trigger raises signals." }, "auto_send": { "type": "boolean", "description": "True sends the message on the day with no review. False puts a draft in front of the broker first." }, "days_offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from the date to act: negative is before it, positive after, from -90 to 90." }, "created_at": { "type": "string", "description": "When the trigger was set up." }, "updated_at": { "type": "string", "description": "Last change. Use it with `updated_since`." } }, "required": [ "object", "id", "broker_id", "type", "subject", "body", "is_active", "auto_send", "days_offset", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/{id}": { "get": { "operationId": "getEquityReport", "summary": "Retrieve an equity report", "description": "One report, as the client received it.", "tags": [ "Equity reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "equity_report", "description": "The type of this record. Always `equity_report`.", "type": "string", "enum": [ "equity_report" ] }, "id": { "type": "string", "description": "Stable identifier for the report." }, "deal_id": { "type": "string", "description": "The deal it was built from." }, "contact_id": { "nullable": true, "description": "The client the report is about: the primary applicant on the deal. Null when the deal has none.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client's name, for display. Null when you cannot read that contact.", "type": "string" }, "month": { "type": "string", "description": "The month the report covers, e.g. `March 2026`." }, "type": { "type": "string", "enum": [ "property", "debt" ], "description": "`property` is the equity report. `debt` is a consolidation report the broker composed." }, "status": { "type": "string", "description": "`sent`, `viewed`, or `interacted`. It says how far the client got." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "description": "How the report reached the client: `email` or `sms`." }, "address": { "nullable": true, "description": "The property, as it read on the report.", "type": "string" }, "property_value": { "nullable": true, "description": "Property value on the report, in dollars.", "type": "number" }, "mortgage_balance": { "nullable": true, "description": "Mortgage balance on the report, in dollars.", "type": "number" }, "equity": { "nullable": true, "description": "Equity on the report, in dollars.", "type": "number" }, "ltv": { "nullable": true, "description": "Loan-to-value on the report, as a percent. `65` means 65%.", "type": "number" }, "heloc_max": { "nullable": true, "description": "The largest line of credit the report showed, in dollars.", "type": "number" }, "viewed_at": { "nullable": true, "description": "When the client first opened the report. Null when they have not.", "type": "string" }, "cta_clicked_at": { "nullable": true, "description": "When the client asked the broker to call. This is the signal worth acting on.", "type": "string" }, "expires_at": { "type": "string", "description": "When the client's link stops working." }, "created_at": { "type": "string", "description": "When the report was created." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "month", "type", "status", "channel", "address", "property_value", "mortgage_balance", "equity", "ltv", "heloc_max", "viewed_at", "cta_clicked_at", "expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/enroll": { "post": { "operationId": "enrollEquityReports", "summary": "Start a client's recurring equity reports", "description": "Enrolls clients in recurring equity reports now, the same as adding clients to recurring reports in BrokerPlus. The response has a line for each deal. Each enrolled client gets their first report when it falls due, at `frequency`. A client who opted out of reports or is under a sanctions freeze is refused, the same as in BrokerPlus. A deal that is already enrolled is `unchanged`; change its cadence with `POST /equity-reports/frequency`. A key with the `no_sending` limit cannot do this.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." }, "frequency": { "default": "monthly", "type": "string", "enum": [ "monthly", "quarterly", "semi_annually", "annually" ], "description": "How often the report goes out: `monthly`, `quarterly`, `semi_annually`, or `annually`." } }, "required": [ "deal_ids", "frequency" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "No deal in the request can take this action (NOTHING_TO_REQUEST), and `details.results` says why for each one. Or BrokerPlus enrolled nobody (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/resume": { "post": { "operationId": "resumeEquityReports", "summary": "Resume paused equity reports", "description": "Restarts the reports of paused clients now. The response has a line for each deal. The reports continue on their cadence. A key with the `no_sending` limit cannot do this.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." } }, "required": [ "deal_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "No deal in the request can take this action (NOTHING_TO_REQUEST), and `details.results` says why for each one. Or BrokerPlus resumed nothing (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/send": { "post": { "operationId": "sendEquityReports", "summary": "Send an equity report now", "description": "Sends each client a one-off equity report now, the same as Send report in BrokerPlus. It does not enroll anybody. The response has a line for each deal. `email` sends from the broker's connected mailbox. `sms` sends a text with the report link. BrokerPlus checks each client's opt-out and consent as it sends, and skips a client who may not receive it. A key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`: a retry with the same key gets the first response and sends nothing again.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." }, "channel": { "default": "email", "description": "`email` sends the report from the broker's connected mailbox. `sms` texts the client a link to it.", "type": "string", "enum": [ "email", "sms" ] }, "sms_body": { "description": "For `sms` only: the text, with merge fields as in BrokerPlus. Omit it to use the brokerage's report text.", "type": "string", "minLength": 1, "maxLength": 1600 } }, "required": [ "deal_ids", "channel" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "No deal in the request can take this action (NOTHING_TO_REQUEST), and `details.results` says why for each one. Or BrokerPlus sent nothing (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/pause": { "post": { "operationId": "pauseEquityReports", "summary": "Pause clients' equity reports", "description": "Pauses the recurring reports of enrolled clients now, the same as a pause in BrokerPlus. The clients stay enrolled and no report goes out until you resume them. A deal that is already paused is `unchanged`. A deal that is not enrolled is `refused`.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." } }, "required": [ "deal_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/unenroll": { "post": { "operationId": "unenrollEquityReports", "summary": "Stop clients' equity reports", "description": "Takes clients off recurring equity reports now, the same as removing them from recurring reports in BrokerPlus. The reports they were already sent stay readable. A deal that is not enrolled is `unchanged`.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." } }, "required": [ "deal_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/equity-reports/frequency": { "post": { "operationId": "setEquityReportFrequency", "summary": "Change how often clients get equity reports", "description": "Sets the cadence of the reports for each deal now. It does not enroll a client, and it sends nothing. A deal with no opportunity yet is `refused`; enroll it first.", "tags": [ "Equity reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "The deals to act on, 1 to 100. A deal is the unit of a report: the client is its primary applicant and the property is its subject property. Find a client's deals with `GET /v1/deals?contact_id=`." }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "semi_annually", "annually" ], "description": "How often the report goes out: `monthly`, `quarterly`, `semi_annually`, or `annually`." } }, "required": [ "deal_ids", "frequency" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal, as you sent it." }, "opportunity_id": { "nullable": true, "description": "The deal's opportunity, which carries its report settings. Null when the deal has none yet.", "type": "string" }, "contact_name": { "nullable": true, "description": "The client the report goes to, for display.", "type": "string" }, "result": { "type": "string", "enum": [ "changed", "unchanged", "refused" ], "description": "`changed`: the change was made now, or the report was sent now. `unchanged`: the deal was already in the state you asked for. `refused`: nothing was done for this deal; `reason` says why." }, "reason": { "nullable": true, "description": "Why a deal was refused or unchanged. `not_found`: no such deal, or your key cannot change it. `locked`: its stage locks the deal. `dismissed`: the broker took it off the book. `unsubscribed`: the client asked to stop getting reports. `frozen`: the client is under a sanctions freeze. `not_enrolled`, `already_enrolled`, `already_paused`, `not_paused`: the enrollment state. `no_opportunity`: the deal has no report settings yet; enroll it first. On a `changed` deal, `no_email` says the client has no email address yet, so no report reaches them until the broker adds one. Null otherwise.", "type": "string", "enum": [ "not_found", "locked", "dismissed", "unsubscribed", "frozen", "not_enrolled", "already_enrolled", "already_paused", "not_paused", "no_opportunity", "no_email", "no_phone" ] } }, "required": [ "deal_id", "opportunity_id", "contact_name", "result", "reason" ], "additionalProperties": false }, "description": "One entry for each deal you sent, in the order you sent them." } }, "required": [ "results" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/reports/pipeline": { "get": { "operationId": "getPipelineReport", "summary": "Read the open pipeline by stage", "description": "The open deals on each stage of the broker's pipelines, with their loan amounts, as the Business pages show them. A funded, lost or archived deal is not counted. The figures are for the key's broker, or for the team broker who shares reports with them.", "tags": [ "Reports" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "broker_id": { "type": "string", "description": "The broker whose book this is: the key's broker, or the team broker who shares reports with them." }, "broker_name": { "type": "string", "description": "The broker's name, for display." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "The stage. Resolve it with `GET /pipelines`." }, "stage_name": { "type": "string", "description": "The stage's name, for display." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the stage sits on its pipeline, from 0." }, "deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Open deals in the stage." }, "priced_deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Of those, the deals with a loan amount. `volume` sums these." }, "volume": { "nullable": true, "description": "The loan amounts in the stage, in dollars. Null when fewer than half of the deals have a loan amount, because the sum would mislead.", "type": "number" } }, "required": [ "stage_id", "stage_name", "position", "deal_count", "priced_deal_count", "volume" ], "additionalProperties": false }, "description": "Every stage on the broker's pipelines, in pipeline order, including an empty stage." }, "totals": { "type": "object", "properties": { "deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Open deals on every stage." }, "volume": { "type": "number", "description": "The loan amounts on every stage that has a `volume`, in dollars." } }, "required": [ "deal_count", "volume" ], "additionalProperties": false, "description": "The sums across the stages." } }, "required": [ "broker_id", "broker_name", "stages", "totals" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker cannot read reports. Their team broker can turn them on (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/reports/funded": { "get": { "operationId": "getFundedReport", "summary": "Read funded volume by month", "description": "The deals that funded in a period, and their volume, in total and for each month, as the Business pages show them. The period is this year to date unless you send another. A period covers at most five years.", "tags": [ "Reports" ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ytd", "qtd", "mtd" ], "default": "ytd" }, "description": "The period to sum: `ytd`, `qtd`, `mtd`. Defaults to `ytd`. Do not send it with `start` and `end`." }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The first day of a custom period, as `YYYY-MM-DD`. Send it with `end`." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The last day of a custom period, as `YYYY-MM-DD`. Send it with `start`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "broker_id": { "type": "string", "description": "The broker whose book this is." }, "broker_name": { "type": "string", "description": "The broker's name, for display." }, "period": { "type": "object", "properties": { "start": { "type": "string", "description": "The first moment the figures cover." }, "end": { "type": "string", "description": "The last moment the figures cover." } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "The period. A deal counts on the day it funded." }, "totals": { "type": "object", "properties": { "deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals that funded in the period, with a commission recorded." }, "volume": { "type": "number", "description": "The funded amounts on those deals, in dollars." } }, "required": [ "deal_count", "volume" ], "additionalProperties": false, "description": "The sums for the period." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "The month, as `YYYY-MM`." }, "deal_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals that funded in the month." }, "volume": { "type": "number", "description": "The funded amounts in the month, in dollars. 0 for a month with none." } }, "required": [ "month", "deal_count", "volume" ], "additionalProperties": false }, "description": "One entry for each month of the period, oldest first, including a month with nothing funded." } }, "required": [ "broker_id", "broker_name", "period", "totals", "months" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The period is not valid, or it covers more than five years (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker cannot read reports. Their team broker can turn them on (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/report-templates": { "get": { "operationId": "listReportTemplates", "summary": "List report templates", "description": "The brokerage's report templates, the layouts a broker saves in the report builder. The most recently changed come first.", "tags": [ "Reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "report_template", "description": "The type of this record. Always `report_template`.", "type": "string", "enum": [ "report_template" ] }, "id": { "type": "string", "description": "Stable identifier for the report template." }, "name": { "type": "string", "description": "The template name, as the report builder shows it." }, "description": { "nullable": true, "description": "What the template is for. Null if the broker did not write one.", "type": "string" }, "layout": { "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false, "description": "The report layout that the report builder in BrokerPlus edits. It holds no client data: each report fills the widgets in from the deal when it is made." }, "created_by_user_id": { "nullable": true, "description": "The broker who made the template. Null if unknown.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template last changed." } }, "required": [ "object", "id", "name", "description", "layout", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createReportTemplate", "summary": "Create a report template", "description": "Saves a report layout as a template for the whole brokerage. Every broker can use it and change it, the same as a template saved in the report builder.", "tags": [ "Reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The template name. At most 200 characters." }, "description": { "description": "What the template is for. At most 1000 characters.", "nullable": true, "type": "string", "maxLength": 1000 }, "layout": { "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false, "description": "The report layout that the report builder in BrokerPlus edits. It holds no client data: each report fills the widgets in from the deal when it is made." } }, "required": [ "name", "layout" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "report_template", "description": "The type of this record. Always `report_template`.", "type": "string", "enum": [ "report_template" ] }, "id": { "type": "string", "description": "Stable identifier for the report template." }, "name": { "type": "string", "description": "The template name, as the report builder shows it." }, "description": { "nullable": true, "description": "What the template is for. Null if the broker did not write one.", "type": "string" }, "layout": { "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false, "description": "The report layout that the report builder in BrokerPlus edits. It holds no client data: each report fills the widgets in from the deal when it is made." }, "created_by_user_id": { "nullable": true, "description": "The broker who made the template. Null if unknown.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template last changed." } }, "required": [ "object", "id", "name", "description", "layout", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A field is missing or not valid, or a widget setting has a value its type cannot use (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/report-templates/{id}": { "get": { "operationId": "getReportTemplate", "summary": "Retrieve a report template", "description": "One report template, with its layout.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "report_template", "description": "The type of this record. Always `report_template`.", "type": "string", "enum": [ "report_template" ] }, "id": { "type": "string", "description": "Stable identifier for the report template." }, "name": { "type": "string", "description": "The template name, as the report builder shows it." }, "description": { "nullable": true, "description": "What the template is for. Null if the broker did not write one.", "type": "string" }, "layout": { "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false, "description": "The report layout that the report builder in BrokerPlus edits. It holds no client data: each report fills the widgets in from the deal when it is made." }, "created_by_user_id": { "nullable": true, "description": "The broker who made the template. Null if unknown.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template last changed." } }, "required": [ "object", "id", "name", "description", "layout", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateReportTemplate", "summary": "Update a report template", "description": "Changes the name, the description, or the layout. A new layout replaces the old one. A bulk report run that already started keeps the layout it started with.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The template name. At most 200 characters.", "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "What the template is for. Send null to clear it.", "nullable": true, "type": "string", "maxLength": 1000 }, "layout": { "description": "The whole new layout. It replaces the old one.", "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "report_template", "description": "The type of this record. Always `report_template`.", "type": "string", "enum": [ "report_template" ] }, "id": { "type": "string", "description": "Stable identifier for the report template." }, "name": { "type": "string", "description": "The template name, as the report builder shows it." }, "description": { "nullable": true, "description": "What the template is for. Null if the broker did not write one.", "type": "string" }, "layout": { "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false, "description": "The report layout that the report builder in BrokerPlus edits. It holds no client data: each report fills the widgets in from the deal when it is made." }, "created_by_user_id": { "nullable": true, "description": "The broker who made the template. Null if unknown.", "type": "string" }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "When the template last changed." } }, "required": [ "object", "id", "name", "description", "layout", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty, or a field is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteReportTemplate", "summary": "Delete a report template", "description": "Deletes the template for the whole brokerage. A bulk report run that used it keeps its reports.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/bulk-report-runs": { "get": { "operationId": "listBulkReportRuns", "summary": "List bulk report runs", "description": "The bulk report runs on the broker's teams, newest first. A run makes one PDF report for each deal it was given.", "tags": [ "Reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "bulk_report_run", "description": "The type of this record. Always `bulk_report_run`.", "type": "string", "enum": [ "bulk_report_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "template_id": { "nullable": true, "description": "The report template the run used. Null when the run was given a layout instead.", "type": "string" }, "template_name": { "type": "string", "description": "The template name when the run started, or `Report` for a layout." }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ], "description": "`pending` until a worker picks the run up, `running` while it makes reports, then `done` or `failed`." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports the run makes." }, "completed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports are made." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports failed." }, "error": { "nullable": true, "description": "Why the whole run failed. Null unless `status` is `failed`.", "type": "string" }, "has_zip": { "type": "boolean", "description": "`true` when the ZIP file with every report is ready to download." }, "created_by_user_id": { "type": "string", "description": "The broker who started the run." }, "created_at": { "type": "string", "description": "When the run started." }, "updated_at": { "type": "string", "description": "When the run last changed." } }, "required": [ "object", "id", "template_id", "template_name", "status", "total", "completed", "failed", "error", "has_zip", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createBulkReportRun", "summary": "Start a bulk report run", "description": "Makes one PDF report for each deal, from a report template or a layout, the same as Bulk Reports in BrokerPlus. The reports are made in the background: poll `GET /bulk-report-runs/{id}`. BrokerPlus sends nothing to the clients.", "tags": [ "Reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "description": "The report template to use. Send this or `layout`. If you send both, the template wins.", "type": "string" }, "layout": { "description": "A layout to use instead of a saved template.", "type": "object", "properties": { "version": { "default": 1, "description": "The layout format. Always `1`.", "type": "number", "enum": [ 1 ] }, "widgets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your identifier for the widget, unique in the layout." }, "type": { "type": "string", "enum": [ "branding_header", "intro_letter", "notes", "broker_cta", "disclaimer", "property_value_hero", "property_details", "equity_snapshot", "borrowing_power", "additional_properties", "mortgage_summary", "mortgage_paydown", "amortization_schedule", "renewal_countdown", "potential_savings", "rate_comparison", "consolidation_summary", "debt_inventory", "deal_summary", "offer_comparison", "scenario_card", "applicant_profile", "affordability_summary", "payment_breakdown", "closing_costs", "down_payment_summary" ], "description": "What the widget shows." }, "order": { "type": "number", "description": "Where the widget sits. Lower numbers come first." }, "hidden": { "description": "`true` keeps the widget and its settings in the layout, but the report does not show it.", "type": "boolean" }, "config": { "default": {}, "description": "The widget's settings. Each type takes its own keys. BrokerPlus refuses a value the type cannot use, and drops a key the type does not know.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "order", "config" ], "additionalProperties": false }, "description": "The widgets in the report, at most 50." } }, "required": [ "version", "widgets" ], "additionalProperties": false }, "deal_ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "The deals to make a report for, one report each, at most 500. A deal the broker cannot read is left out." } }, "required": [ "deal_ids" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "bulk_report_run", "description": "The type of this record. Always `bulk_report_run`.", "type": "string", "enum": [ "bulk_report_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "template_id": { "nullable": true, "description": "The report template the run used. Null when the run was given a layout instead.", "type": "string" }, "template_name": { "type": "string", "description": "The template name when the run started, or `Report` for a layout." }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ], "description": "`pending` until a worker picks the run up, `running` while it makes reports, then `done` or `failed`." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports the run makes." }, "completed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports are made." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports failed." }, "error": { "nullable": true, "description": "Why the whole run failed. Null unless `status` is `failed`.", "type": "string" }, "has_zip": { "type": "boolean", "description": "`true` when the ZIP file with every report is ready to download." }, "created_by_user_id": { "type": "string", "description": "The broker who started the run." }, "created_at": { "type": "string", "description": "When the run started." }, "updated_at": { "type": "string", "description": "When the run last changed." } }, "required": [ "object", "id", "template_id", "template_name", "status", "total", "completed", "failed", "error", "has_zip", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Neither `template_id` nor `layout` was sent, or a field is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The template does not exist, or none of the deals exist or the broker cannot read them (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The saved template has a layout BrokerPlus can no longer read. Save the template again (INVALID_LAYOUT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/bulk-report-runs/{id}": { "get": { "operationId": "getBulkReportRun", "summary": "Retrieve a bulk report run", "description": "One run, with each report and its status. Poll this until `status` is `done` or `failed`, then get the files with `GET /bulk-report-runs/{id}/files`.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "bulk_report_run", "description": "The type of this record. Always `bulk_report_run`.", "type": "string", "enum": [ "bulk_report_run" ] }, "id": { "type": "string", "description": "Stable identifier for the run." }, "template_id": { "nullable": true, "description": "The report template the run used. Null when the run was given a layout instead.", "type": "string" }, "template_name": { "type": "string", "description": "The template name when the run started, or `Report` for a layout." }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ], "description": "`pending` until a worker picks the run up, `running` while it makes reports, then `done` or `failed`." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports the run makes." }, "completed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports are made." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many reports failed." }, "error": { "nullable": true, "description": "Why the whole run failed. Null unless `status` is `failed`.", "type": "string" }, "has_zip": { "type": "boolean", "description": "`true` when the ZIP file with every report is ready to download." }, "created_by_user_id": { "type": "string", "description": "The broker who started the run." }, "created_at": { "type": "string", "description": "When the run started." }, "updated_at": { "type": "string", "description": "When the run last changed." }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "bulk_report_item", "description": "The type of this record. Always `bulk_report_item`.", "type": "string", "enum": [ "bulk_report_item" ] }, "id": { "type": "string", "description": "Stable identifier for the report in the run." }, "deal_id": { "type": "string", "description": "The deal the report is made from." }, "person_name": { "nullable": true, "description": "The client the report is for. Null until the report is made.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "done", "failed" ], "description": "`pending` until the report is made, then `done` or `failed`." }, "error": { "nullable": true, "description": "Why the report failed. Null unless `status` is `failed`.", "type": "string" }, "has_pdf": { "type": "boolean", "description": "`true` when the PDF is ready to download." } }, "required": [ "object", "id", "deal_id", "person_name", "status", "error", "has_pdf" ], "additionalProperties": false }, "description": "One report for each deal, in the order the run made them." } }, "required": [ "object", "id", "template_id", "template_name", "status", "total", "completed", "failed", "error", "has_zip", "created_by_user_id", "created_at", "updated_at", "items" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/bulk-report-runs/{id}/files": { "get": { "operationId": "getBulkReportRunFiles", "summary": "Get the files of a bulk report run", "description": "Links to the PDF of each report that is ready, and to the ZIP file with all of them. Each link stops working after 1 hour: call again for new links.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "run_id": { "type": "string", "description": "The run the files are from." }, "zip_url": { "nullable": true, "description": "A link to the ZIP file with every report. Null until the run makes it. The link stops working after 1 hour.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The report in the run." }, "deal_id": { "type": "string", "description": "The deal the report is made from." }, "person_name": { "nullable": true, "description": "The client the report is for.", "type": "string" }, "url": { "type": "string", "description": "A link to the PDF. The link stops working after 1 hour." } }, "required": [ "id", "deal_id", "person_name", "url" ], "additionalProperties": false }, "description": "A link for each report that is ready. A report that is pending or failed is not listed." }, "expires_at": { "type": "string", "description": "When the links stop working." } }, "required": [ "run_id", "zip_url", "items", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-runs": { "get": { "operationId": "listImportRuns", "summary": "List imports", "description": "The imports on the broker's teams, newest first, as the Import page lists them. An import brings one or more files or syncs into the book. Each import lists its sources with what was read and what failed.", "tags": [ "Data hub" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_run", "description": "The type of this record. Always `import_run`.", "type": "string", "enum": [ "import_run" ] }, "id": { "type": "string", "description": "Stable identifier for the import." }, "status": { "type": "string", "enum": [ "staging", "resolving", "staged", "activating", "active", "removing", "removed", "failed", "expired" ], "description": "Where the import is: `staging` and `resolving` while the sources are read and matched, `staged` when it waits for the broker to review it, `activating` while it is added to the book, `active` when it is in the book, `removing` and `removed` after the broker took it back out, and `failed`." }, "created_by_user_id": { "nullable": true, "description": "The broker who started the import.", "type": "string" }, "staged_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals ready to import, after matching." }, "staged_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts ready to import, after matching." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read, across every source." }, "excluded_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals left out because the broker excluded their agent." }, "activated_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals that were added to the book. 0 until the import is active." }, "activated_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts that were added to the book. 0 until the import is active." }, "failure_reason": { "nullable": true, "description": "Why the import stopped, in words a broker can act on. Null if it did not.", "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_source", "description": "The type of this record. Always `import_source`.", "type": "string", "enum": [ "import_source" ] }, "id": { "type": "string", "description": "Stable identifier for the source." }, "provider": { "type": "string", "enum": [ "csv", "xlsx", "scarlett", "filogix", "zoho", "pipedrive", "ghl", "gomax", "jungo", "salesforce", "brokerplus_v1", "finmo", "velocity", "inbox" ], "description": "Where the source came from: a file's system, or a connected system for a sync." }, "name": { "type": "string", "description": "What the broker calls the source. A file's name by default." }, "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "What the source holds: deals, or contacts." }, "mode": { "type": "string", "enum": [ "additive", "overwrite" ], "description": "`additive` fills in only what a matched record does not have. `overwrite` replaces what it has with what the source says." }, "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The source's priority in the import. When two sources disagree, the lower number wins." }, "enabled": { "type": "boolean", "description": "`false` when the broker switched the source off. It is listed but not imported." }, "status": { "type": "string", "enum": [ "queued", "staging", "staged", "failed" ], "description": "`queued` until it is read, `staging` while it is read, then `staged` or `failed`." }, "staged_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that were read and are ready to import." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read." }, "blocked_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Problems that stop the import until the broker fixes them in BrokerPlus, such as a column to correct." }, "failure_reason": { "nullable": true, "description": "Why the source failed, in words a broker can act on. Null if it did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the source was added." } }, "required": [ "object", "id", "provider", "name", "kind", "mode", "rank", "enabled", "status", "staged_records", "failed_records", "blocked_records", "failure_reason", "created_at" ], "additionalProperties": false }, "description": "The files and syncs in the import, in priority order." }, "staged_at": { "nullable": true, "description": "When every source was read and matched. Null before then.", "type": "string" }, "activated_at": { "nullable": true, "description": "When the import was added to the book. Null before then.", "type": "string" }, "removed_at": { "nullable": true, "description": "When the broker removed the import. Null if they did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the import started." }, "updated_at": { "type": "string", "description": "When the import last changed." } }, "required": [ "object", "id", "status", "created_by_user_id", "staged_deals", "staged_contacts", "failed_records", "excluded_deals", "activated_deals", "activated_contacts", "failure_reason", "sources", "staged_at", "activated_at", "removed_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-runs/{id}": { "get": { "operationId": "getImportRun", "summary": "Retrieve an import", "description": "One import, its status, and its sources in priority order.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "import_run", "description": "The type of this record. Always `import_run`.", "type": "string", "enum": [ "import_run" ] }, "id": { "type": "string", "description": "Stable identifier for the import." }, "status": { "type": "string", "enum": [ "staging", "resolving", "staged", "activating", "active", "removing", "removed", "failed", "expired" ], "description": "Where the import is: `staging` and `resolving` while the sources are read and matched, `staged` when it waits for the broker to review it, `activating` while it is added to the book, `active` when it is in the book, `removing` and `removed` after the broker took it back out, and `failed`." }, "created_by_user_id": { "nullable": true, "description": "The broker who started the import.", "type": "string" }, "staged_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals ready to import, after matching." }, "staged_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts ready to import, after matching." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read, across every source." }, "excluded_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals left out because the broker excluded their agent." }, "activated_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals that were added to the book. 0 until the import is active." }, "activated_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts that were added to the book. 0 until the import is active." }, "failure_reason": { "nullable": true, "description": "Why the import stopped, in words a broker can act on. Null if it did not.", "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_source", "description": "The type of this record. Always `import_source`.", "type": "string", "enum": [ "import_source" ] }, "id": { "type": "string", "description": "Stable identifier for the source." }, "provider": { "type": "string", "enum": [ "csv", "xlsx", "scarlett", "filogix", "zoho", "pipedrive", "ghl", "gomax", "jungo", "salesforce", "brokerplus_v1", "finmo", "velocity", "inbox" ], "description": "Where the source came from: a file's system, or a connected system for a sync." }, "name": { "type": "string", "description": "What the broker calls the source. A file's name by default." }, "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "What the source holds: deals, or contacts." }, "mode": { "type": "string", "enum": [ "additive", "overwrite" ], "description": "`additive` fills in only what a matched record does not have. `overwrite` replaces what it has with what the source says." }, "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The source's priority in the import. When two sources disagree, the lower number wins." }, "enabled": { "type": "boolean", "description": "`false` when the broker switched the source off. It is listed but not imported." }, "status": { "type": "string", "enum": [ "queued", "staging", "staged", "failed" ], "description": "`queued` until it is read, `staging` while it is read, then `staged` or `failed`." }, "staged_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that were read and are ready to import." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read." }, "blocked_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Problems that stop the import until the broker fixes them in BrokerPlus, such as a column to correct." }, "failure_reason": { "nullable": true, "description": "Why the source failed, in words a broker can act on. Null if it did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the source was added." } }, "required": [ "object", "id", "provider", "name", "kind", "mode", "rank", "enabled", "status", "staged_records", "failed_records", "blocked_records", "failure_reason", "created_at" ], "additionalProperties": false }, "description": "The files and syncs in the import, in priority order." }, "staged_at": { "nullable": true, "description": "When every source was read and matched. Null before then.", "type": "string" }, "activated_at": { "nullable": true, "description": "When the import was added to the book. Null before then.", "type": "string" }, "removed_at": { "nullable": true, "description": "When the broker removed the import. Null if they did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the import started." }, "updated_at": { "type": "string", "description": "When the import last changed." } }, "required": [ "object", "id", "status", "created_by_user_id", "staged_deals", "staged_contacts", "failed_records", "excluded_deals", "activated_deals", "activated_contacts", "failure_reason", "sources", "staged_at", "activated_at", "removed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-runs/files": { "post": { "operationId": "uploadImportFile", "summary": "Add a deals file to an import", "description": "Adds a deals export (`.csv`, `.xlsx` or `.xls`) to the team's open import, or starts one, the same as an upload on the Import page. Send the file as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. BrokerPlus reads and maps it in the background: poll `GET /import-runs/{id}`. Nothing is added to the book until the broker reviews the import and adds it in BrokerPlus.", "tags": [ "Data hub" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file: a `.csv`, `.xlsx` or `.xls` export. At most 100 MB." }, "provider": { "description": "The system the file was exported from.", "type": "string", "enum": [ "csv", "xlsx", "scarlett", "filogix", "zoho", "pipedrive", "ghl", "gomax", "jungo", "salesforce", "brokerplus_v1" ] }, "mode": { "description": "`additive` (the default) or `overwrite`.", "type": "string", "enum": [ "additive", "overwrite" ] }, "name": { "description": "A name for the source. The file name by default.", "type": "string" } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file name, with its extension: `.csv`, `.xlsx` or `.xls`. BrokerPlus also reads it to guess the provider." }, "content_base64": { "type": "string", "minLength": 1, "description": "The file's bytes as standard base64. At most 100 MB before encoding." }, "provider": { "description": "The system the file was exported from. Leave it out and BrokerPlus reads it from the file.", "type": "string", "enum": [ "csv", "xlsx", "scarlett", "filogix", "zoho", "pipedrive", "ghl", "gomax", "jungo", "salesforce", "brokerplus_v1" ] }, "mode": { "default": "additive", "description": "`additive` (the default) fills in only what a deal already in the book does not have. `overwrite` replaces it with what the file says.", "type": "string", "enum": [ "additive", "overwrite" ] }, "name": { "description": "A name for the source. The file name by default.", "type": "string", "maxLength": 200 } }, "required": [ "file_name", "content_base64", "mode" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "import_run", "description": "The type of this record. Always `import_run`.", "type": "string", "enum": [ "import_run" ] }, "id": { "type": "string", "description": "Stable identifier for the import." }, "status": { "type": "string", "enum": [ "staging", "resolving", "staged", "activating", "active", "removing", "removed", "failed", "expired" ], "description": "Where the import is: `staging` and `resolving` while the sources are read and matched, `staged` when it waits for the broker to review it, `activating` while it is added to the book, `active` when it is in the book, `removing` and `removed` after the broker took it back out, and `failed`." }, "created_by_user_id": { "nullable": true, "description": "The broker who started the import.", "type": "string" }, "staged_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals ready to import, after matching." }, "staged_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts ready to import, after matching." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read, across every source." }, "excluded_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals left out because the broker excluded their agent." }, "activated_deals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals that were added to the book. 0 until the import is active." }, "activated_contacts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Contacts that were added to the book. 0 until the import is active." }, "failure_reason": { "nullable": true, "description": "Why the import stopped, in words a broker can act on. Null if it did not.", "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_source", "description": "The type of this record. Always `import_source`.", "type": "string", "enum": [ "import_source" ] }, "id": { "type": "string", "description": "Stable identifier for the source." }, "provider": { "type": "string", "enum": [ "csv", "xlsx", "scarlett", "filogix", "zoho", "pipedrive", "ghl", "gomax", "jungo", "salesforce", "brokerplus_v1", "finmo", "velocity", "inbox" ], "description": "Where the source came from: a file's system, or a connected system for a sync." }, "name": { "type": "string", "description": "What the broker calls the source. A file's name by default." }, "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "What the source holds: deals, or contacts." }, "mode": { "type": "string", "enum": [ "additive", "overwrite" ], "description": "`additive` fills in only what a matched record does not have. `overwrite` replaces what it has with what the source says." }, "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The source's priority in the import. When two sources disagree, the lower number wins." }, "enabled": { "type": "boolean", "description": "`false` when the broker switched the source off. It is listed but not imported." }, "status": { "type": "string", "enum": [ "queued", "staging", "staged", "failed" ], "description": "`queued` until it is read, `staging` while it is read, then `staged` or `failed`." }, "staged_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that were read and are ready to import." }, "failed_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rows that could not be read." }, "blocked_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Problems that stop the import until the broker fixes them in BrokerPlus, such as a column to correct." }, "failure_reason": { "nullable": true, "description": "Why the source failed, in words a broker can act on. Null if it did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the source was added." } }, "required": [ "object", "id", "provider", "name", "kind", "mode", "rank", "enabled", "status", "staged_records", "failed_records", "blocked_records", "failure_reason", "created_at" ], "additionalProperties": false }, "description": "The files and syncs in the import, in priority order." }, "staged_at": { "nullable": true, "description": "When every source was read and matched. Null before then.", "type": "string" }, "activated_at": { "nullable": true, "description": "When the import was added to the book. Null before then.", "type": "string" }, "removed_at": { "nullable": true, "description": "When the broker removed the import. Null if they did not.", "type": "string" }, "created_at": { "type": "string", "description": "When the import started." }, "updated_at": { "type": "string", "description": "When the import last changed." } }, "required": [ "object", "id", "status", "created_by_user_id", "staged_deals", "staged_contacts", "failed_records", "excluded_deals", "activated_deals", "activated_contacts", "failure_reason", "sources", "staged_at", "activated_at", "removed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing, not valid base64, or has no sheet BrokerPlus can read (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is on no team (NO_TEAM), or cannot change imports (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "Another import holds the team's place: it is being added to the book, or it stopped part-way (RUN_BUSY or INVALID_STATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "The file is larger than 100 MB (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-status-routes": { "get": { "operationId": "listImportStatusRoutes", "summary": "List import status routes", "description": "Where an import sends a deal by the status word the other system wrote, as Settings > Import shows it. The routes are the brokerage's, and every import uses them.", "tags": [ "Data hub" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_status_route", "description": "The type of this record. Always `import_status_route`.", "type": "string", "enum": [ "import_status_route" ] }, "id": { "type": "string", "description": "Stable identifier for the route." }, "source_status": { "type": "string", "description": "The status word as the other system writes it, in lowercase. For example `ready to close`." }, "deal_type": { "nullable": true, "description": "The deal type this route is for. Null is the route for every type that has no route of its own.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "placement": { "nullable": true, "description": "Where a deal with this status goes when no stage is chosen: the matching stage on the right pipeline. Null when a stage is chosen.", "type": "string", "enum": [ "imported", "open", "submitted", "approved", "funded", "closed", "not_proceeding", "declined" ] }, "board_id": { "nullable": true, "description": "The pipeline the broker chose. Null when `placement` decides.", "type": "string" }, "board_stage_id": { "nullable": true, "description": "The stage the broker chose on that pipeline.", "type": "string" }, "origin": { "type": "string", "enum": [ "broker", "system" ], "description": "`broker` when a person chose the route. `system` when BrokerPlus proposed it; BrokerPlus can change those, never a broker's." }, "created_at": { "type": "string", "description": "When the route was first saved." }, "updated_at": { "type": "string", "description": "When the route last changed." } }, "required": [ "object", "id", "source_status", "deal_type", "placement", "board_id", "board_stage_id", "origin", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "setImportStatusRoutes", "summary": "Save import status routes", "description": "Saves the routes you send, the same as the mapping form in Settings > Import, and leaves every other route as it is. A route names a pipeline and stage, or a placement. Send neither to delete the route. A pipeline the key's broker cannot change, or a stage that is not on it, is left out of the route. Imports that already ran keep where they put the deals.", "tags": [ "Data hub" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "source_status": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The status word as the other system writes it." }, "deal_type": { "description": "The deal type the route is for. Leave it out, or send null, for every type.", "nullable": true, "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "board_id": { "description": "The pipeline to send the deals to. It must be one the key's broker can change.", "nullable": true, "type": "string" }, "board_stage_id": { "description": "The stage on that pipeline.", "nullable": true, "type": "string" }, "placement": { "description": "Where the deals go when you send no pipeline. Send no pipeline and no placement to delete the route.", "nullable": true, "type": "string", "enum": [ "imported", "open", "submitted", "approved", "funded", "closed", "not_proceeding", "declined" ] } }, "required": [ "source_status" ], "additionalProperties": false }, "description": "The routes to save, at most 500. A route you do not send stays as it is." } }, "required": [ "entries" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "written": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many routes were saved or deleted." }, "routes": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_status_route", "description": "The type of this record. Always `import_status_route`.", "type": "string", "enum": [ "import_status_route" ] }, "id": { "type": "string", "description": "Stable identifier for the route." }, "source_status": { "type": "string", "description": "The status word as the other system writes it, in lowercase. For example `ready to close`." }, "deal_type": { "nullable": true, "description": "The deal type this route is for. Null is the route for every type that has no route of its own.", "type": "string", "enum": [ "purchase", "preapproval", "refinance_same_lender", "refinance_diff_lender", "renewal_same_lender", "renewal_diff_lender", "heloc", "reverse_mortgage" ] }, "placement": { "nullable": true, "description": "Where a deal with this status goes when no stage is chosen: the matching stage on the right pipeline. Null when a stage is chosen.", "type": "string", "enum": [ "imported", "open", "submitted", "approved", "funded", "closed", "not_proceeding", "declined" ] }, "board_id": { "nullable": true, "description": "The pipeline the broker chose. Null when `placement` decides.", "type": "string" }, "board_stage_id": { "nullable": true, "description": "The stage the broker chose on that pipeline.", "type": "string" }, "origin": { "type": "string", "enum": [ "broker", "system" ], "description": "`broker` when a person chose the route. `system` when BrokerPlus proposed it; BrokerPlus can change those, never a broker's." }, "created_at": { "type": "string", "description": "When the route was first saved." }, "updated_at": { "type": "string", "description": "When the route last changed." } }, "required": [ "object", "id", "source_status", "deal_type", "placement", "board_id", "board_stage_id", "origin", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every route the brokerage has, after the save." } }, "required": [ "written", "routes" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A route is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-mappings": { "get": { "operationId": "listImportMappings", "summary": "List saved import mappings", "description": "The column mappings the brokerage saved from past imports, newest change first. The next file with the same column headers is mapped the same way.", "tags": [ "Data hub" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "import_mapping", "description": "The type of this record. Always `import_mapping`.", "type": "string", "enum": [ "import_mapping" ] }, "id": { "type": "string", "description": "Stable identifier for the saved mapping." }, "signature": { "type": "string", "description": "A fingerprint of the file's column headers. The next file with the same headers gets this mapping." }, "name": { "nullable": true, "description": "The broker's name for the mapping. Null if they did not give one.", "type": "string" }, "source_label": { "nullable": true, "description": "The system the file came from, when BrokerPlus knows it.", "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The column header in the file." }, "field_key": { "type": "string", "minLength": 1, "description": "The BrokerPlus field the column fills, for example `applicant.firstName`." }, "applicant_index": { "default": 0, "description": "Which borrower the column is about, from 0 for the main borrower.", "type": "integer", "minimum": 0, "maximum": 20 }, "list_index": { "default": 0, "description": "Which item of a list the column fills, from 0, such as the second job.", "type": "integer", "minimum": 0, "maximum": 200 }, "method": { "default": "alias", "description": "How the column was matched to the field. `alias` for a column a person chose.", "type": "string", "enum": [ "alias", "registry", "fuzzy", "llm" ] } }, "required": [ "header", "field_key", "applicant_index", "list_index", "method" ], "additionalProperties": false }, "description": "Which BrokerPlus field each column fills." }, "created_by_user_id": { "nullable": true, "description": "The broker whose import saved the mapping.", "type": "string" }, "created_at": { "type": "string", "description": "When the mapping was saved." }, "updated_at": { "type": "string", "description": "When the mapping last changed." } }, "required": [ "object", "id", "signature", "name", "source_label", "columns", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/import-mappings/{id}": { "get": { "operationId": "getImportMapping", "summary": "Retrieve a saved import mapping", "description": "One saved mapping and the field each column fills.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "import_mapping", "description": "The type of this record. Always `import_mapping`.", "type": "string", "enum": [ "import_mapping" ] }, "id": { "type": "string", "description": "Stable identifier for the saved mapping." }, "signature": { "type": "string", "description": "A fingerprint of the file's column headers. The next file with the same headers gets this mapping." }, "name": { "nullable": true, "description": "The broker's name for the mapping. Null if they did not give one.", "type": "string" }, "source_label": { "nullable": true, "description": "The system the file came from, when BrokerPlus knows it.", "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The column header in the file." }, "field_key": { "type": "string", "minLength": 1, "description": "The BrokerPlus field the column fills, for example `applicant.firstName`." }, "applicant_index": { "default": 0, "description": "Which borrower the column is about, from 0 for the main borrower.", "type": "integer", "minimum": 0, "maximum": 20 }, "list_index": { "default": 0, "description": "Which item of a list the column fills, from 0, such as the second job.", "type": "integer", "minimum": 0, "maximum": 200 }, "method": { "default": "alias", "description": "How the column was matched to the field. `alias` for a column a person chose.", "type": "string", "enum": [ "alias", "registry", "fuzzy", "llm" ] } }, "required": [ "header", "field_key", "applicant_index", "list_index", "method" ], "additionalProperties": false }, "description": "Which BrokerPlus field each column fills." }, "created_by_user_id": { "nullable": true, "description": "The broker whose import saved the mapping.", "type": "string" }, "created_at": { "type": "string", "description": "When the mapping was saved." }, "updated_at": { "type": "string", "description": "When the mapping last changed." } }, "required": [ "object", "id", "signature", "name", "source_label", "columns", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateImportMapping", "summary": "Update a saved import mapping", "description": "Renames the mapping or replaces its columns, the same as Settings > Import. Only a key that belongs to a brokerage admin can change a saved mapping. An import that already ran keeps how it was mapped.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A name for the mapping. Send null to clear it.", "nullable": true, "type": "string", "maxLength": 200 }, "columns": { "description": "The whole new column list. It replaces the old one.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The column header in the file." }, "field_key": { "type": "string", "minLength": 1, "description": "The BrokerPlus field the column fills, for example `applicant.firstName`." }, "applicant_index": { "default": 0, "description": "Which borrower the column is about, from 0 for the main borrower.", "type": "integer", "minimum": 0, "maximum": 20 }, "list_index": { "default": 0, "description": "Which item of a list the column fills, from 0, such as the second job.", "type": "integer", "minimum": 0, "maximum": 200 }, "method": { "default": "alias", "description": "How the column was matched to the field. `alias` for a column a person chose.", "type": "string", "enum": [ "alias", "registry", "fuzzy", "llm" ] } }, "required": [ "header", "field_key", "applicant_index", "list_index", "method" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "import_mapping", "description": "The type of this record. Always `import_mapping`.", "type": "string", "enum": [ "import_mapping" ] }, "id": { "type": "string", "description": "Stable identifier for the saved mapping." }, "signature": { "type": "string", "description": "A fingerprint of the file's column headers. The next file with the same headers gets this mapping." }, "name": { "nullable": true, "description": "The broker's name for the mapping. Null if they did not give one.", "type": "string" }, "source_label": { "nullable": true, "description": "The system the file came from, when BrokerPlus knows it.", "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The column header in the file." }, "field_key": { "type": "string", "minLength": 1, "description": "The BrokerPlus field the column fills, for example `applicant.firstName`." }, "applicant_index": { "default": 0, "description": "Which borrower the column is about, from 0 for the main borrower.", "type": "integer", "minimum": 0, "maximum": 20 }, "list_index": { "default": 0, "description": "Which item of a list the column fills, from 0, such as the second job.", "type": "integer", "minimum": 0, "maximum": 200 }, "method": { "default": "alias", "description": "How the column was matched to the field. `alias` for a column a person chose.", "type": "string", "enum": [ "alias", "registry", "fuzzy", "llm" ] } }, "required": [ "header", "field_key", "applicant_index", "list_index", "method" ], "additionalProperties": false }, "description": "Which BrokerPlus field each column fills." }, "created_by_user_id": { "nullable": true, "description": "The broker whose import saved the mapping.", "type": "string" }, "created_at": { "type": "string", "description": "When the mapping was saved." }, "updated_at": { "type": "string", "description": "When the mapping last changed." } }, "required": [ "object", "id", "signature", "name", "source_label", "columns", "created_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty, a field is not valid, or a column names a field BrokerPlus does not have (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteImportMapping", "summary": "Delete a saved import mapping", "description": "Deletes the mapping for the whole brokerage. The next file with the same headers is mapped from scratch. Only a key that belongs to a brokerage admin can delete one.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/goals": { "get": { "operationId": "listGoals", "summary": "List goals", "description": "The broker's goals, with where they stand today, as the goals card on the Business pages shows them. This is the key's broker's goals, or the team broker's when they share reports with them, and every goal that covers the whole brokerage. `pace` is worked out from the funded deals each time you read it.", "tags": [ "Reports" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "goal", "description": "The type of this record. Always `goal`.", "type": "string", "enum": [ "goal" ] }, "id": { "type": "string", "description": "Stable identifier for the goal." }, "metric": { "type": "string", "enum": [ "funded_volume", "funded_units", "net_commission" ], "description": "What the goal counts: `funded_volume` is the funded amounts in dollars, `funded_units` is the number of deals funded, and `net_commission` is the broker's commission in dollars." }, "broker_id": { "nullable": true, "description": "The broker the goal is for. Null for a goal that covers the whole brokerage.", "type": "string" }, "lender_id": { "nullable": true, "description": "Set on a lender status goal, which counts only the deals funded with this lender. Null for the whole book.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, for display. Null for the whole book.", "type": "string" }, "tier_name": { "nullable": true, "description": "The broker's name for the lender status they are working toward, for example `Platinum`. For display only.", "type": "string" }, "period_start": { "type": "string", "description": "The first day the goal covers." }, "period_end": { "type": "string", "description": "The last day the goal covers." }, "target": { "type": "number", "description": "The target for the whole period, in the goal's `metric`." }, "curve": { "type": "string", "enum": [ "straight_line", "seasonal" ], "description": "How the target is spread over the months: `straight_line` evenly, `seasonal` heavier in the spring and the summer, as mortgage business is." }, "monthly_overrides": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "The broker's own target for some months, keyed `YYYY-MM`. A month named here takes that target, and the rest of the goal is spread over the other months." }, "pace": { "type": "object", "properties": { "actual": { "type": "number", "description": "What the broker achieved in the period so far, as the Business pages count it." }, "expected": { "type": "number", "description": "What the broker should have achieved by today, along the goal's curve." }, "gap": { "type": "number", "description": "`actual` minus `expected`. Negative means behind." }, "status": { "type": "string", "enum": [ "ahead", "on_track", "slightly_behind", "behind" ], "description": "How the broker is doing against `expected`. Up to 10% short is `on_track`, up to 25% short is `slightly_behind`." }, "progress": { "type": "number", "description": "The share of the whole target achieved so far. 1 means the target is met; it can be more than 1." }, "projected": { "nullable": true, "description": "What the period ends at if the broker keeps the current rate. Null before the period starts.", "type": "number" }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "The month, as `YYYY-MM`." }, "target": { "type": "number", "description": "The target for the month." } }, "required": [ "month", "target" ], "additionalProperties": false }, "description": "The target for each month of the period, oldest first." } }, "required": [ "actual", "expected", "gap", "status", "progress", "projected", "monthly" ], "additionalProperties": false, "description": "Where the broker stands today, worked out from the funded deals each time you read the goal." }, "gap_in_deals": { "nullable": true, "description": "The gap restated as a number of deals of the broker's average size. Null for a `funded_units` goal, or when nothing funded yet.", "type": "number" }, "within_reach": { "type": "boolean", "description": "True when the broker has reached 85% of the target but not all of it, so one more deal may get them there." }, "created_at": { "type": "string", "description": "When the goal was set." }, "updated_at": { "type": "string", "description": "When the goal last changed." } }, "required": [ "object", "id", "metric", "broker_id", "lender_id", "lender_name", "tier_name", "period_start", "period_end", "target", "curve", "monthly_overrides", "pace", "gap_in_deals", "within_reach", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`updated_since` is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker cannot read reports. Their team broker can turn them on (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createGoal", "summary": "Set a goal", "description": "Sets a goal for the key's broker. A goal is named by its `metric`, `period_start` and `lender_id`: if the broker already has a goal with the same three, this replaces its target and settings. A key cannot set a goal for another broker, or for the whole brokerage. Supports `Idempotency-Key`.", "tags": [ "Reports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "funded_volume", "funded_units", "net_commission" ], "description": "What the goal counts: `funded_volume` is the funded amounts in dollars, `funded_units` is the number of deals funded, and `net_commission` is the broker's commission in dollars." }, "period_start": { "type": "string", "description": "The first day the goal covers. With `metric` and `lender_id`, it names the goal: a second goal with the same three replaces the first." }, "period_end": { "type": "string", "description": "The last day the goal covers. It must be after `period_start`." }, "target": { "type": "number", "minimum": 0, "description": "The target for the whole period, in the goal's `metric`." }, "curve": { "description": "How the target is spread over the months. Default `straight_line`.", "type": "string", "enum": [ "straight_line", "seasonal" ] }, "monthly_overrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "The broker's own target for some months, keyed `YYYY-MM`. A month named here takes that target, and the rest of the goal is spread over the other months." }, "lender_id": { "description": "Count only the deals funded with this lender, for a lender status goal. Find it with `GET /v1/lenders`. Leave it out for the whole book.", "nullable": true, "type": "string" }, "tier_name": { "description": "Your name for the lender status, for example `Platinum`. At most 60 characters.", "nullable": true, "type": "string", "maxLength": 60 } }, "required": [ "metric", "period_start", "period_end", "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "goal", "description": "The type of this record. Always `goal`.", "type": "string", "enum": [ "goal" ] }, "id": { "type": "string", "description": "Stable identifier for the goal." }, "metric": { "type": "string", "enum": [ "funded_volume", "funded_units", "net_commission" ], "description": "What the goal counts: `funded_volume` is the funded amounts in dollars, `funded_units` is the number of deals funded, and `net_commission` is the broker's commission in dollars." }, "broker_id": { "nullable": true, "description": "The broker the goal is for. Null for a goal that covers the whole brokerage.", "type": "string" }, "lender_id": { "nullable": true, "description": "Set on a lender status goal, which counts only the deals funded with this lender. Null for the whole book.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, for display. Null for the whole book.", "type": "string" }, "tier_name": { "nullable": true, "description": "The broker's name for the lender status they are working toward, for example `Platinum`. For display only.", "type": "string" }, "period_start": { "type": "string", "description": "The first day the goal covers." }, "period_end": { "type": "string", "description": "The last day the goal covers." }, "target": { "type": "number", "description": "The target for the whole period, in the goal's `metric`." }, "curve": { "type": "string", "enum": [ "straight_line", "seasonal" ], "description": "How the target is spread over the months: `straight_line` evenly, `seasonal` heavier in the spring and the summer, as mortgage business is." }, "monthly_overrides": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "The broker's own target for some months, keyed `YYYY-MM`. A month named here takes that target, and the rest of the goal is spread over the other months." }, "pace": { "type": "object", "properties": { "actual": { "type": "number", "description": "What the broker achieved in the period so far, as the Business pages count it." }, "expected": { "type": "number", "description": "What the broker should have achieved by today, along the goal's curve." }, "gap": { "type": "number", "description": "`actual` minus `expected`. Negative means behind." }, "status": { "type": "string", "enum": [ "ahead", "on_track", "slightly_behind", "behind" ], "description": "How the broker is doing against `expected`. Up to 10% short is `on_track`, up to 25% short is `slightly_behind`." }, "progress": { "type": "number", "description": "The share of the whole target achieved so far. 1 means the target is met; it can be more than 1." }, "projected": { "nullable": true, "description": "What the period ends at if the broker keeps the current rate. Null before the period starts.", "type": "number" }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "The month, as `YYYY-MM`." }, "target": { "type": "number", "description": "The target for the month." } }, "required": [ "month", "target" ], "additionalProperties": false }, "description": "The target for each month of the period, oldest first." } }, "required": [ "actual", "expected", "gap", "status", "progress", "projected", "monthly" ], "additionalProperties": false, "description": "Where the broker stands today, worked out from the funded deals each time you read the goal." }, "gap_in_deals": { "nullable": true, "description": "The gap restated as a number of deals of the broker's average size. Null for a `funded_units` goal, or when nothing funded yet.", "type": "number" }, "within_reach": { "type": "boolean", "description": "True when the broker has reached 85% of the target but not all of it, so one more deal may get them there." }, "created_at": { "type": "string", "description": "When the goal was set." }, "updated_at": { "type": "string", "description": "When the goal last changed." } }, "required": [ "object", "id", "metric", "broker_id", "lender_id", "lender_name", "tier_name", "period_start", "period_end", "target", "curve", "monthly_overrides", "pace", "gap_in_deals", "within_reach", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is not valid, or `period_end` is not after `period_start` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The lender does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/goals/{id}": { "get": { "operationId": "getGoal", "summary": "Retrieve a goal", "description": "One goal, with where the broker stands against it today.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "goal", "description": "The type of this record. Always `goal`.", "type": "string", "enum": [ "goal" ] }, "id": { "type": "string", "description": "Stable identifier for the goal." }, "metric": { "type": "string", "enum": [ "funded_volume", "funded_units", "net_commission" ], "description": "What the goal counts: `funded_volume` is the funded amounts in dollars, `funded_units` is the number of deals funded, and `net_commission` is the broker's commission in dollars." }, "broker_id": { "nullable": true, "description": "The broker the goal is for. Null for a goal that covers the whole brokerage.", "type": "string" }, "lender_id": { "nullable": true, "description": "Set on a lender status goal, which counts only the deals funded with this lender. Null for the whole book.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, for display. Null for the whole book.", "type": "string" }, "tier_name": { "nullable": true, "description": "The broker's name for the lender status they are working toward, for example `Platinum`. For display only.", "type": "string" }, "period_start": { "type": "string", "description": "The first day the goal covers." }, "period_end": { "type": "string", "description": "The last day the goal covers." }, "target": { "type": "number", "description": "The target for the whole period, in the goal's `metric`." }, "curve": { "type": "string", "enum": [ "straight_line", "seasonal" ], "description": "How the target is spread over the months: `straight_line` evenly, `seasonal` heavier in the spring and the summer, as mortgage business is." }, "monthly_overrides": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "The broker's own target for some months, keyed `YYYY-MM`. A month named here takes that target, and the rest of the goal is spread over the other months." }, "pace": { "type": "object", "properties": { "actual": { "type": "number", "description": "What the broker achieved in the period so far, as the Business pages count it." }, "expected": { "type": "number", "description": "What the broker should have achieved by today, along the goal's curve." }, "gap": { "type": "number", "description": "`actual` minus `expected`. Negative means behind." }, "status": { "type": "string", "enum": [ "ahead", "on_track", "slightly_behind", "behind" ], "description": "How the broker is doing against `expected`. Up to 10% short is `on_track`, up to 25% short is `slightly_behind`." }, "progress": { "type": "number", "description": "The share of the whole target achieved so far. 1 means the target is met; it can be more than 1." }, "projected": { "nullable": true, "description": "What the period ends at if the broker keeps the current rate. Null before the period starts.", "type": "number" }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "The month, as `YYYY-MM`." }, "target": { "type": "number", "description": "The target for the month." } }, "required": [ "month", "target" ], "additionalProperties": false }, "description": "The target for each month of the period, oldest first." } }, "required": [ "actual", "expected", "gap", "status", "progress", "projected", "monthly" ], "additionalProperties": false, "description": "Where the broker stands today, worked out from the funded deals each time you read the goal." }, "gap_in_deals": { "nullable": true, "description": "The gap restated as a number of deals of the broker's average size. Null for a `funded_units` goal, or when nothing funded yet.", "type": "number" }, "within_reach": { "type": "boolean", "description": "True when the broker has reached 85% of the target but not all of it, so one more deal may get them there." }, "created_at": { "type": "string", "description": "When the goal was set." }, "updated_at": { "type": "string", "description": "When the goal last changed." } }, "required": [ "object", "id", "metric", "broker_id", "lender_id", "lender_name", "tier_name", "period_start", "period_end", "target", "curve", "monthly_overrides", "pace", "gap_in_deals", "within_reach", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker cannot read reports. Their team broker can turn them on (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateGoal", "summary": "Change a goal", "description": "Changes the target, the end of the period, the curve, the months the broker set by hand, or the status name. To change the metric, the start or the lender, set a new goal and delete this one. Only the key's broker's own goals can change.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period_end": { "description": "The last day the goal covers. It must be after `period_start`.", "type": "string" }, "target": { "description": "The target for the whole period, in the goal's `metric`.", "type": "number", "minimum": 0 }, "curve": { "type": "string", "enum": [ "straight_line", "seasonal" ], "description": "How the target is spread over the months: `straight_line` evenly, `seasonal` heavier in the spring and the summer, as mortgage business is." }, "monthly_overrides": { "description": "The broker's own target for some months, keyed `YYYY-MM`. Send null to spread the whole target along the curve again.", "nullable": true, "type": "object", "additionalProperties": { "type": "number", "minimum": 0 } }, "tier_name": { "description": "Your name for the lender status. Send null to clear it.", "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "goal", "description": "The type of this record. Always `goal`.", "type": "string", "enum": [ "goal" ] }, "id": { "type": "string", "description": "Stable identifier for the goal." }, "metric": { "type": "string", "enum": [ "funded_volume", "funded_units", "net_commission" ], "description": "What the goal counts: `funded_volume` is the funded amounts in dollars, `funded_units` is the number of deals funded, and `net_commission` is the broker's commission in dollars." }, "broker_id": { "nullable": true, "description": "The broker the goal is for. Null for a goal that covers the whole brokerage.", "type": "string" }, "lender_id": { "nullable": true, "description": "Set on a lender status goal, which counts only the deals funded with this lender. Null for the whole book.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, for display. Null for the whole book.", "type": "string" }, "tier_name": { "nullable": true, "description": "The broker's name for the lender status they are working toward, for example `Platinum`. For display only.", "type": "string" }, "period_start": { "type": "string", "description": "The first day the goal covers." }, "period_end": { "type": "string", "description": "The last day the goal covers." }, "target": { "type": "number", "description": "The target for the whole period, in the goal's `metric`." }, "curve": { "type": "string", "enum": [ "straight_line", "seasonal" ], "description": "How the target is spread over the months: `straight_line` evenly, `seasonal` heavier in the spring and the summer, as mortgage business is." }, "monthly_overrides": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "The broker's own target for some months, keyed `YYYY-MM`. A month named here takes that target, and the rest of the goal is spread over the other months." }, "pace": { "type": "object", "properties": { "actual": { "type": "number", "description": "What the broker achieved in the period so far, as the Business pages count it." }, "expected": { "type": "number", "description": "What the broker should have achieved by today, along the goal's curve." }, "gap": { "type": "number", "description": "`actual` minus `expected`. Negative means behind." }, "status": { "type": "string", "enum": [ "ahead", "on_track", "slightly_behind", "behind" ], "description": "How the broker is doing against `expected`. Up to 10% short is `on_track`, up to 25% short is `slightly_behind`." }, "progress": { "type": "number", "description": "The share of the whole target achieved so far. 1 means the target is met; it can be more than 1." }, "projected": { "nullable": true, "description": "What the period ends at if the broker keeps the current rate. Null before the period starts.", "type": "number" }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "The month, as `YYYY-MM`." }, "target": { "type": "number", "description": "The target for the month." } }, "required": [ "month", "target" ], "additionalProperties": false }, "description": "The target for each month of the period, oldest first." } }, "required": [ "actual", "expected", "gap", "status", "progress", "projected", "monthly" ], "additionalProperties": false, "description": "Where the broker stands today, worked out from the funded deals each time you read the goal." }, "gap_in_deals": { "nullable": true, "description": "The gap restated as a number of deals of the broker's average size. Null for a `funded_units` goal, or when nothing funded yet.", "type": "number" }, "within_reach": { "type": "boolean", "description": "True when the broker has reached 85% of the target but not all of it, so one more deal may get them there." }, "created_at": { "type": "string", "description": "When the goal was set." }, "updated_at": { "type": "string", "description": "When the goal last changed." } }, "required": [ "object", "id", "metric", "broker_id", "lender_id", "lender_name", "tier_name", "period_start", "period_end", "target", "curve", "monthly_overrides", "pace", "gap_in_deals", "within_reach", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty or not valid, or `period_end` is not after `period_start` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The goal does not exist, or it is not the key's broker's own (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteGoal", "summary": "Delete a goal", "description": "Deletes one of the key's broker's goals, or a goal that covers the whole brokerage.", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The goal does not exist, or the key's broker cannot delete it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/data-exports/packages": { "get": { "operationId": "listDataExportPackages", "summary": "List data export packages", "description": "The packages a broker can export, as the Export page shows them. Send a package's `id` as `package_id`.", "tags": [ "Data hub" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "data_export_package", "description": "The type of this record. Always `data_export_package`.", "type": "string", "enum": [ "data_export_package" ] }, "id": { "type": "string", "description": "The package to send as `package_id`, for example `contacts`, or `takeout` for everything." }, "label": { "type": "string", "description": "The package name, as BrokerPlus shows it." }, "description": { "type": "string", "description": "What the package holds." } }, "required": [ "object", "id", "label", "description" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/data-exports": { "get": { "operationId": "listDataExports", "summary": "List data exports", "description": "The exports the key's broker requested, newest first. Another broker's exports are never listed, the same as in BrokerPlus.", "tags": [ "Data hub" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "data_export", "description": "The type of this record. Always `data_export`.", "type": "string", "enum": [ "data_export" ] }, "id": { "type": "string", "description": "Stable identifier for the export." }, "package_id": { "type": "string", "description": "The package the export holds. See `GET /v1/data-exports/packages`." }, "status": { "type": "string", "enum": [ "pending", "running", "ready", "failed", "cancelled" ], "description": "`pending` until a worker picks the export up, `running` while it is built, then `ready`, `failed`, or `cancelled`." }, "error": { "nullable": true, "description": "Why the export failed. Null unless `status` is `failed`.", "type": "string" }, "total_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps the build has. 0 until the build starts." }, "completed_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps are done." }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows the export holds, across every table. 0 until it is ready." }, "volumes": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part number, from 1." }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the part, in bytes." }, "sha256": { "type": "string", "description": "The SHA-256 digest of the part, to check a download." } }, "required": [ "index", "bytes", "sha256" ], "additionalProperties": false }, "description": "The ZIP files of the export. A large export is split into more than one part." }, "total_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of every part together, in bytes." }, "created_at": { "type": "string", "description": "When the export was requested." }, "completed_at": { "nullable": true, "description": "When the export was ready, failed, or was cancelled.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the files are deleted. After this, request a new export.", "type": "string" }, "expired_at": { "nullable": true, "description": "When the files were deleted. Null while they can be downloaded.", "type": "string" } }, "required": [ "object", "id", "package_id", "status", "error", "total_steps", "completed_steps", "row_count", "volumes", "total_bytes", "created_at", "completed_at", "expires_at", "expired_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDataExport", "summary": "Request a data export", "description": "Starts an export of one package, built in the background from the records the key's broker can read. If an export of the same package is already pending or running, you get that export. The files stay for 30 days. Download them in BrokerPlus: the API does not give the files.", "tags": [ "Data hub" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package_id": { "type": "string", "minLength": 1, "description": "The package to export. Get the packages from `GET /v1/data-exports/packages`." } }, "required": [ "package_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "data_export", "description": "The type of this record. Always `data_export`.", "type": "string", "enum": [ "data_export" ] }, "id": { "type": "string", "description": "Stable identifier for the export." }, "package_id": { "type": "string", "description": "The package the export holds. See `GET /v1/data-exports/packages`." }, "status": { "type": "string", "enum": [ "pending", "running", "ready", "failed", "cancelled" ], "description": "`pending` until a worker picks the export up, `running` while it is built, then `ready`, `failed`, or `cancelled`." }, "error": { "nullable": true, "description": "Why the export failed. Null unless `status` is `failed`.", "type": "string" }, "total_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps the build has. 0 until the build starts." }, "completed_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps are done." }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows the export holds, across every table. 0 until it is ready." }, "volumes": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part number, from 1." }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the part, in bytes." }, "sha256": { "type": "string", "description": "The SHA-256 digest of the part, to check a download." } }, "required": [ "index", "bytes", "sha256" ], "additionalProperties": false }, "description": "The ZIP files of the export. A large export is split into more than one part." }, "total_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of every part together, in bytes." }, "created_at": { "type": "string", "description": "When the export was requested." }, "completed_at": { "nullable": true, "description": "When the export was ready, failed, or was cancelled.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the files are deleted. After this, request a new export.", "type": "string" }, "expired_at": { "nullable": true, "description": "When the files were deleted. Null while they can be downloaded.", "type": "string" } }, "required": [ "object", "id", "package_id", "status", "error", "total_steps", "completed_steps", "row_count", "volumes", "total_bytes", "created_at", "completed_at", "expires_at", "expired_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "There is no package with that `package_id` (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/data-exports/{id}": { "get": { "operationId": "getDataExport", "summary": "Retrieve a data export", "description": "One export and how far its build is. Poll this until `status` is `ready`, then download the files in BrokerPlus.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "data_export", "description": "The type of this record. Always `data_export`.", "type": "string", "enum": [ "data_export" ] }, "id": { "type": "string", "description": "Stable identifier for the export." }, "package_id": { "type": "string", "description": "The package the export holds. See `GET /v1/data-exports/packages`." }, "status": { "type": "string", "enum": [ "pending", "running", "ready", "failed", "cancelled" ], "description": "`pending` until a worker picks the export up, `running` while it is built, then `ready`, `failed`, or `cancelled`." }, "error": { "nullable": true, "description": "Why the export failed. Null unless `status` is `failed`.", "type": "string" }, "total_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps the build has. 0 until the build starts." }, "completed_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps are done." }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows the export holds, across every table. 0 until it is ready." }, "volumes": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part number, from 1." }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the part, in bytes." }, "sha256": { "type": "string", "description": "The SHA-256 digest of the part, to check a download." } }, "required": [ "index", "bytes", "sha256" ], "additionalProperties": false }, "description": "The ZIP files of the export. A large export is split into more than one part." }, "total_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of every part together, in bytes." }, "created_at": { "type": "string", "description": "When the export was requested." }, "completed_at": { "nullable": true, "description": "When the export was ready, failed, or was cancelled.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the files are deleted. After this, request a new export.", "type": "string" }, "expired_at": { "nullable": true, "description": "When the files were deleted. Null while they can be downloaded.", "type": "string" } }, "required": [ "object", "id", "package_id", "status", "error", "total_steps", "completed_steps", "row_count", "volumes", "total_bytes", "created_at", "completed_at", "expires_at", "expired_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/data-exports/{id}/cancel": { "post": { "operationId": "cancelDataExport", "summary": "Cancel a data export", "description": "Stops an export that is pending or running.", "tags": [ "Data hub" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "data_export", "description": "The type of this record. Always `data_export`.", "type": "string", "enum": [ "data_export" ] }, "id": { "type": "string", "description": "Stable identifier for the export." }, "package_id": { "type": "string", "description": "The package the export holds. See `GET /v1/data-exports/packages`." }, "status": { "type": "string", "enum": [ "pending", "running", "ready", "failed", "cancelled" ], "description": "`pending` until a worker picks the export up, `running` while it is built, then `ready`, `failed`, or `cancelled`." }, "error": { "nullable": true, "description": "Why the export failed. Null unless `status` is `failed`.", "type": "string" }, "total_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps the build has. 0 until the build starts." }, "completed_steps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many steps are done." }, "row_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows the export holds, across every table. 0 until it is ready." }, "volumes": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part number, from 1." }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of the part, in bytes." }, "sha256": { "type": "string", "description": "The SHA-256 digest of the part, to check a download." } }, "required": [ "index", "bytes", "sha256" ], "additionalProperties": false }, "description": "The ZIP files of the export. A large export is split into more than one part." }, "total_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The size of every part together, in bytes." }, "created_at": { "type": "string", "description": "When the export was requested." }, "completed_at": { "nullable": true, "description": "When the export was ready, failed, or was cancelled.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the files are deleted. After this, request a new export.", "type": "string" }, "expired_at": { "nullable": true, "description": "When the files were deleted. Null while they can be downloaded.", "type": "string" } }, "required": [ "object", "id", "package_id", "status", "error", "total_steps", "completed_steps", "row_count", "volumes", "total_bytes", "created_at", "completed_at", "expires_at", "expired_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The export has already finished (CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/referral-partners": { "get": { "operationId": "listReferralPartners", "summary": "Read the referral partner book", "description": "Every referral partner in the brokerage, with what they sent the broker and what the broker sent them, as the Partners page shows it. The figures cover the whole history unless you send a period. This is one summary, not a paged list.", "tags": [ "Referral partners" ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "ytd", "qtd", "mtd" ], "default": "all" }, "description": "The period to sum: `all`, `ytd`, `qtd`, `mtd`. Defaults to `all`. Do not send it with `start` and `end`." }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The first day of a custom period, as `YYYY-MM-DD`. Send it with `end`." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The last day of a custom period, as `YYYY-MM-DD`. Send it with `start`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string", "description": "The first moment the figures cover." }, "end": { "type": "string", "description": "The last moment the figures cover." } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "The period the figures cover. People count on the day they were referred, money on the day it funded." }, "totals": { "type": "object", "properties": { "received": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People referred to the broker by all partners." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People the broker introduced to all partners." }, "funded_volume": { "type": "number", "description": "Dollars funded on deals credited to a partner." }, "gross_commission": { "type": "number", "description": "The broker's gross commission on those deals, in dollars." } }, "required": [ "received", "sent", "funded_volume", "gross_commission" ], "additionalProperties": false, "description": "The sums across every partner." }, "unattributed_leads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Leads in the period with no partner. They are in no row." }, "partners": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "referral_partner", "description": "The type of this record. Always `referral_partner`.", "type": "string", "enum": [ "referral_partner" ] }, "id": { "type": "string", "description": "The partner's id. It is their contact id, or `source:` and an id for a partner who is not a contact. Use it as it is." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "nullable": true, "description": "The partner's name.", "type": "string" }, "contact_info": { "nullable": true, "description": "An email address or a phone number for the partner, for display.", "type": "string" }, "type": { "nullable": true, "description": "What the partner is, e.g. `realtor` or `lawyer`. Null when nobody said.", "type": "string" }, "company": { "nullable": true, "description": "The firm the partner works for.", "type": "string" }, "received": { "type": "object", "properties": { "people": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People the partner referred to the broker in the period." }, "converted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Of those people, how many have since funded a deal." }, "funded_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals credited to the partner that funded in the period." }, "funded_volume": { "type": "number", "description": "The dollars those deals funded." }, "gross_commission": { "type": "number", "description": "The broker's gross commission on those deals, in dollars." } }, "required": [ "people", "converted", "funded_count", "funded_volume", "gross_commission" ], "additionalProperties": false, "description": "What the partner sent the broker." }, "sent": { "type": "object", "properties": { "people": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People the broker introduced to the partner in the period." }, "value": { "nullable": true, "description": "The property price behind those introductions, in dollars. Null when no introduction had a price.", "type": "number" } }, "required": [ "people", "value" ], "additionalProperties": false, "description": "What the broker sent the partner." }, "last_contact_at": { "nullable": true, "description": "The last message between the broker and the partner, on any channel, in any period. Null when there is none.", "type": "string" }, "reciprocity": { "nullable": true, "description": "People sent divided by people received, as a ratio. Null when the partner sent nobody.", "type": "number" }, "avg_deal_size": { "nullable": true, "description": "Funded volume divided by funded deals, in dollars. Null when nothing funded.", "type": "number" }, "conversion_rate": { "nullable": true, "description": "The share of the people referred in the period who have since funded, as a percent. `25` means 25%. Null when nobody was referred.", "type": "number" } }, "required": [ "object", "id", "contact_id", "name", "contact_info", "type", "company", "received", "sent", "last_contact_at", "reciprocity", "avg_deal_size", "conversion_rate" ], "additionalProperties": false }, "description": "Every partner in the brokerage, including a partner with nothing in the period." } }, "required": [ "period", "totals", "unattributed_leads", "partners" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The period is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/referral-partners/{id}": { "get": { "operationId": "getReferralPartner", "summary": "Retrieve a referral partner", "description": "One partner with the people they referred, the deals that funded, and the people the broker introduced to them. Use an `id` from `GET /referral-partners` or from a deal's `referral_partner`. The totals cover the whole brokerage. A key limited to teams lists only the people and deals its teams can read.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "ytd", "qtd", "mtd" ], "default": "all" }, "description": "The period to sum: `all`, `ytd`, `qtd`, `mtd`. Defaults to `all`. Do not send it with `start` and `end`." }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The first day of a custom period, as `YYYY-MM-DD`. Send it with `end`." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "The last day of a custom period, as `YYYY-MM-DD`. Send it with `start`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string", "description": "The first moment the figures cover." }, "end": { "type": "string", "description": "The last moment the figures cover." } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "The period the figures cover. People count on the day they were referred, money on the day it funded." }, "partner": { "type": "object", "properties": { "id": { "type": "string", "description": "The partner's id. It is their contact id, or `source:` and an id for a partner who is not a contact. Use it as it is." }, "contact_id": { "nullable": true, "description": "The partner's contact. Null for a partner known only by name.", "type": "string" }, "name": { "type": "string", "description": "The partner's name." }, "contact_info": { "nullable": true, "description": "An email address or a phone number for the partner.", "type": "string" }, "type": { "nullable": true, "description": "What the partner is. Null when nobody said.", "type": "string" }, "company": { "nullable": true, "description": "The firm the partner works for.", "type": "string" }, "last_contact_at": { "nullable": true, "description": "The last message between the broker and the partner.", "type": "string" }, "next_follow_up_at": { "nullable": true, "description": "When the broker plans to contact the partner next.", "type": "string" } }, "required": [ "id", "contact_id", "name", "contact_info", "type", "company", "last_contact_at", "next_follow_up_at" ], "additionalProperties": false, "description": "Who the partner is." }, "totals": { "type": "object", "properties": { "received": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People the partner referred in the period." }, "sent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People the broker introduced to the partner in the period." }, "funded_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Deals credited to the partner that funded in the period." }, "funded_volume": { "type": "number", "description": "The dollars those deals funded." }, "gross_commission": { "type": "number", "description": "The broker's gross commission on those deals, in dollars." }, "avg_deal_size": { "nullable": true, "description": "Funded volume divided by funded deals. Null when nothing funded.", "type": "number" }, "conversion_rate": { "nullable": true, "description": "The share of the people referred who have since funded, as a percent. `25` means 25%. Null when nobody was referred.", "type": "number" }, "reciprocity": { "nullable": true, "description": "People sent divided by people received. Null when none received.", "type": "number" } }, "required": [ "received", "sent", "funded_count", "funded_volume", "gross_commission", "avg_deal_size", "conversion_rate", "reciprocity" ], "additionalProperties": false, "description": "The partner's figures for the period." }, "referred": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "nullable": true, "description": "The person the partner referred.", "type": "string" }, "name": { "type": "string", "description": "Their name." }, "via": { "type": "string", "enum": [ "referral", "lead", "deal" ], "description": "How the credit reached the partner: a referral the broker logged, a lead, or a deal." }, "occurred_at": { "type": "string", "description": "When the person was referred." }, "status": { "nullable": true, "description": "The status of their deal or lead.", "type": "string" }, "deal_id": { "nullable": true, "description": "Their deal, when there is one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "funded_at": { "nullable": true, "description": "When their deal funded.", "type": "string" }, "credited_to": { "nullable": true, "description": "The partner the funded deal credits instead, when it is not this one. Null otherwise.", "type": "string" } }, "required": [ "contact_id", "name", "via", "occurred_at", "status", "deal_id", "deal_name", "funded_at", "credited_to" ], "additionalProperties": false }, "description": "The people the partner referred in the period." }, "funded_deals": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal." }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "client_names": { "type": "array", "items": { "type": "string" }, "description": "The borrowers on the deal." }, "funded_at": { "nullable": true, "description": "When the deal funded.", "type": "string" }, "funded_volume": { "type": "number", "description": "The dollars the deal funded." }, "gross_commission": { "type": "number", "description": "The broker's gross commission on the deal, in dollars." } }, "required": [ "deal_id", "deal_name", "client_names", "funded_at", "funded_volume", "gross_commission" ], "additionalProperties": false }, "description": "The deals credited to the partner that funded in the period." }, "introductions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The introduction." }, "contact_id": { "type": "string", "description": "The person the broker introduced to the partner." }, "name": { "type": "string", "description": "Their name." }, "occurred_at": { "type": "string", "description": "When the broker made the introduction." }, "note": { "nullable": true, "description": "The broker's note on the introduction.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal behind the introduction, when there is one.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" } }, "required": [ "id", "contact_id", "name", "occurred_at", "note", "deal_id", "deal_name" ], "additionalProperties": false }, "description": "The people the broker introduced to the partner in the period." } }, "required": [ "period", "partner", "totals", "referred", "funded_deals", "introductions" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The period is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contact-referrals": { "get": { "operationId": "listContactReferrals", "summary": "List referrals between contacts", "description": "Who referred whom, newest referral first: each row is one person and the contact who sent them to the broker. A referral is listed when the broker can see the referred person. Filter by `referrer_contact_id` for everyone one partner sent.", "tags": [ "Referral partners" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "referrer_contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only people this contact referred." }, { "name": "referred_contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the referral of this person." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only referrals linked to this deal." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ] }, "description": "Only referrals in this status." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ] }, "description": "Only referrals of this kind." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "contact_referral", "description": "The type of this record. Always `contact_referral`.", "type": "string", "enum": [ "contact_referral" ] }, "id": { "type": "string", "description": "Stable identifier for the referral." }, "referrer_contact_id": { "type": "string", "description": "The contact who made the referral." }, "referrer_name": { "nullable": true, "description": "The referrer's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "referred_contact_id": { "type": "string", "description": "The contact who was referred. A contact has at most one referrer." }, "referred_name": { "nullable": true, "description": "The referred person's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the referral turned into. Null until one is linked.", "type": "string" }, "source": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ], "description": "What kind of person made the referral, for example `realtor` or `past_client`." }, "status": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ], "description": "Where the referred person is: `received`, `contacted`, `in_progress`, `funded` or `dead`. BrokerPlus sets `funded` itself when the linked deal funds." }, "note": { "nullable": true, "description": "The broker's note about the referral.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the referral was made." }, "created_at": { "type": "string", "description": "When the referral was recorded." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "referrer_contact_id", "referrer_name", "referred_contact_id", "referred_name", "deal_id", "source", "status", "note", "occurred_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createContactReferral", "summary": "Record who referred a contact", "description": "Records that one contact referred another, as Referred By on the contact page does. A person has one referrer: if the referred contact already has one, the referral is replaced, its other fields are kept unless you send them, and the response is `200` instead of `201`.", "tags": [ "Referral partners" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "referrer_contact_id": { "type": "string", "minLength": 1, "description": "The contact who made the referral." }, "referred_contact_id": { "type": "string", "minLength": 1, "description": "The contact who was referred. If this contact already has a referrer, the referral is replaced and the response is `200` rather than `201`." }, "source": { "description": "Defaults to `other`.", "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ] }, "status": { "description": "Defaults to `received`.", "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ] }, "note": { "description": "The broker's note about the referral.", "type": "string", "maxLength": 20000 }, "deal_id": { "description": "The deal the referral turned into.", "type": "string" }, "occurred_at": { "description": "When the referral was made. Defaults to now.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "referrer_contact_id", "referred_contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_referral", "description": "The type of this record. Always `contact_referral`.", "type": "string", "enum": [ "contact_referral" ] }, "id": { "type": "string", "description": "Stable identifier for the referral." }, "referrer_contact_id": { "type": "string", "description": "The contact who made the referral." }, "referrer_name": { "nullable": true, "description": "The referrer's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "referred_contact_id": { "type": "string", "description": "The contact who was referred. A contact has at most one referrer." }, "referred_name": { "nullable": true, "description": "The referred person's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the referral turned into. Null until one is linked.", "type": "string" }, "source": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ], "description": "What kind of person made the referral, for example `realtor` or `past_client`." }, "status": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ], "description": "Where the referred person is: `received`, `contacted`, `in_progress`, `funded` or `dead`. BrokerPlus sets `funded` itself when the linked deal funds." }, "note": { "nullable": true, "description": "The broker's note about the referral.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the referral was made." }, "created_at": { "type": "string", "description": "When the referral was recorded." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "referrer_contact_id", "referrer_name", "referred_contact_id", "referred_name", "deal_id", "source", "status", "note", "occurred_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The referrer and the referred person are the same contact (INVALID_REFERRAL).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "A contact or the deal does not exist, or the broker cannot change the referred contact (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contact-referrals/{id}": { "get": { "operationId": "getContactReferral", "summary": "Retrieve a referral", "description": "One referral, with the names of the referrer and the referred person.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_referral", "description": "The type of this record. Always `contact_referral`.", "type": "string", "enum": [ "contact_referral" ] }, "id": { "type": "string", "description": "Stable identifier for the referral." }, "referrer_contact_id": { "type": "string", "description": "The contact who made the referral." }, "referrer_name": { "nullable": true, "description": "The referrer's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "referred_contact_id": { "type": "string", "description": "The contact who was referred. A contact has at most one referrer." }, "referred_name": { "nullable": true, "description": "The referred person's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the referral turned into. Null until one is linked.", "type": "string" }, "source": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ], "description": "What kind of person made the referral, for example `realtor` or `past_client`." }, "status": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ], "description": "Where the referred person is: `received`, `contacted`, `in_progress`, `funded` or `dead`. BrokerPlus sets `funded` itself when the linked deal funds." }, "note": { "nullable": true, "description": "The broker's note about the referral.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the referral was made." }, "created_at": { "type": "string", "description": "When the referral was recorded." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "referrer_contact_id", "referrer_name", "referred_contact_id", "referred_name", "deal_id", "source", "status", "note", "occurred_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateContactReferral", "summary": "Update a referral", "description": "Changes the kind, status, note, linked deal or date of a referral. Only the fields you send change. To change who made the referral, record it again with `POST /v1/contact-referrals`.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ], "description": "What kind of person made the referral, for example `realtor` or `past_client`." }, "status": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ], "description": "Where the referred person is: `received`, `contacted`, `in_progress`, `funded` or `dead`. BrokerPlus sets `funded` itself when the linked deal funds." }, "note": { "description": "The note. `null` clears it.", "nullable": true, "type": "string", "maxLength": 20000 }, "deal_id": { "description": "The deal the referral turned into. `null` unlinks it.", "nullable": true, "type": "string" }, "occurred_at": { "description": "When the referral was made.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "contact_referral", "description": "The type of this record. Always `contact_referral`.", "type": "string", "enum": [ "contact_referral" ] }, "id": { "type": "string", "description": "Stable identifier for the referral." }, "referrer_contact_id": { "type": "string", "description": "The contact who made the referral." }, "referrer_name": { "nullable": true, "description": "The referrer's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "referred_contact_id": { "type": "string", "description": "The contact who was referred. A contact has at most one referrer." }, "referred_name": { "nullable": true, "description": "The referred person's name, for display. Null if the broker cannot see that contact.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal the referral turned into. Null until one is linked.", "type": "string" }, "source": { "type": "string", "enum": [ "realtor", "lawyer", "past_client", "financial_planner", "insurance", "builder", "partner", "self_generated", "other" ], "description": "What kind of person made the referral, for example `realtor` or `past_client`." }, "status": { "type": "string", "enum": [ "received", "contacted", "in_progress", "funded", "dead" ], "description": "Where the referred person is: `received`, `contacted`, `in_progress`, `funded` or `dead`. BrokerPlus sets `funded` itself when the linked deal funds." }, "note": { "nullable": true, "description": "The broker's note about the referral.", "type": "string" }, "occurred_at": { "type": "string", "description": "When the referral was made." }, "created_at": { "type": "string", "description": "When the referral was recorded." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "referrer_contact_id", "referrer_name", "referred_contact_id", "referred_name", "deal_id", "source", "status", "note", "occurred_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The referral or the deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteContactReferral", "summary": "Delete a referral", "description": "Removes the referral. Both contacts stay in the book.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-hubs": { "get": { "operationId": "listPartnerHubs", "summary": "List partner hubs", "description": "The partner hubs the broker opened, newest first. A partner hub is one page where a referral partner sees every file they are on with the broker. Use `q` to find the hub for a partner by name. A partner with no hub is not listed: open one with `POST /partner-hubs`.", "tags": [ "Referral partners" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Text search over the partner's name, company, email and phone. Every word must match part of one of them. The same search as the search bar in BrokerPlus." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the hub for this partner contact." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_hub", "description": "The type of this record. Always `partner_hub`.", "type": "string", "enum": [ "partner_hub" ] }, "id": { "type": "string", "description": "Stable identifier for the partner hub." }, "contact_id": { "type": "string", "description": "The partner's contact." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "notify_stage_changes": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on moves to a new stage. Off until the broker turns it on." }, "notify_funded": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on funds. Off until the broker turns it on." }, "show_funded": { "type": "boolean", "description": "The hub lists the files that funded. On until the broker turns it off. Open files are always listed." }, "show_not_proceeding": { "type": "boolean", "description": "The hub lists the files that ended without funding, such as cancelled or declined files. On until the broker turns it off. Open files are always listed." }, "revoked_at": { "nullable": true, "description": "When the broker turned the hub off. Every link then stops working. Null while the hub is on.", "type": "string" }, "last_sent_at": { "nullable": true, "description": "When the broker last emailed the hub to the partner. Null if never.", "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_hub_link", "description": "The type of this record. Always `partner_hub_link`.", "type": "string", "enum": [ "partner_hub_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "hub_id": { "type": "string", "description": "The partner hub that the link opens." }, "channel": { "type": "string", "enum": [ "send", "copy", "notice" ], "description": "How the link left BrokerPlus: `send` in the broker's email to the partner, `copy` copied by the broker or issued through the API, `notice` in an update email to the partner." }, "recipient_email": { "nullable": true, "description": "The address the link was emailed to. Null for a copied link.", "type": "string" }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the partner opened the link." }, "last_viewed_at": { "nullable": true, "description": "When the partner last opened the link. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was issued." } }, "required": [ "object", "id", "hub_id", "channel", "recipient_email", "view_count", "last_viewed_at", "created_at" ], "additionalProperties": false }, "description": "The links that still work, newest first, at most 10. A link does not include its address: issue a new link with `POST /v1/partner-hubs/{id}/link` to get one." }, "created_at": { "type": "string", "description": "When the hub was opened." }, "updated_at": { "type": "string", "description": "When the hub settings last changed." } }, "required": [ "object", "id", "contact_id", "partner_name", "notify_stage_changes", "notify_funded", "show_funded", "show_not_proceeding", "revoked_at", "last_sent_at", "links", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createPartnerHub", "summary": "Open a partner hub and issue a link", "description": "Opens the partner hub for a contact and issues a link to it in `link.url`. If the partner already has a hub, you get that hub and a new link. If the broker turned the hub off, this turns it on again. Send `show_funded` or `show_not_proceeding` to choose which finished files the hub lists. BrokerPlus sends nothing: give the link to the partner yourself.", "tags": [ "Referral partners" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The partner's contact. Find it with `GET /v1/contacts` or from `contact_id` in `GET /v1/referral-partners`." }, "show_funded": { "description": "Set to `false` to remove the files that funded from the hub. If you omit it, the hub keeps its value.", "type": "boolean" }, "show_not_proceeding": { "description": "Set to `false` to remove the files that ended without funding from the hub. If you omit it, the hub keeps its value.", "type": "boolean" } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_hub", "description": "The type of this record. Always `partner_hub`.", "type": "string", "enum": [ "partner_hub" ] }, "id": { "type": "string", "description": "Stable identifier for the partner hub." }, "contact_id": { "type": "string", "description": "The partner's contact." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "notify_stage_changes": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on moves to a new stage. Off until the broker turns it on." }, "notify_funded": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on funds. Off until the broker turns it on." }, "show_funded": { "type": "boolean", "description": "The hub lists the files that funded. On until the broker turns it off. Open files are always listed." }, "show_not_proceeding": { "type": "boolean", "description": "The hub lists the files that ended without funding, such as cancelled or declined files. On until the broker turns it off. Open files are always listed." }, "revoked_at": { "nullable": true, "description": "When the broker turned the hub off. Every link then stops working. Null while the hub is on.", "type": "string" }, "last_sent_at": { "nullable": true, "description": "When the broker last emailed the hub to the partner. Null if never.", "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_hub_link", "description": "The type of this record. Always `partner_hub_link`.", "type": "string", "enum": [ "partner_hub_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "hub_id": { "type": "string", "description": "The partner hub that the link opens." }, "channel": { "type": "string", "enum": [ "send", "copy", "notice" ], "description": "How the link left BrokerPlus: `send` in the broker's email to the partner, `copy` copied by the broker or issued through the API, `notice` in an update email to the partner." }, "recipient_email": { "nullable": true, "description": "The address the link was emailed to. Null for a copied link.", "type": "string" }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the partner opened the link." }, "last_viewed_at": { "nullable": true, "description": "When the partner last opened the link. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was issued." } }, "required": [ "object", "id", "hub_id", "channel", "recipient_email", "view_count", "last_viewed_at", "created_at" ], "additionalProperties": false }, "description": "The links that still work, newest first, at most 10. A link does not include its address: issue a new link with `POST /v1/partner-hubs/{id}/link` to get one." }, "created_at": { "type": "string", "description": "When the hub was opened." }, "updated_at": { "type": "string", "description": "When the hub settings last changed." }, "link": { "type": "object", "properties": { "object": { "default": "partner_hub_link", "description": "The type of this record. Always `partner_hub_link`.", "type": "string", "enum": [ "partner_hub_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "hub_id": { "type": "string", "description": "The partner hub that the link opens." }, "channel": { "type": "string", "enum": [ "send", "copy", "notice" ], "description": "How the link left BrokerPlus: `send` in the broker's email to the partner, `copy` copied by the broker or issued through the API, `notice` in an update email to the partner." }, "recipient_email": { "nullable": true, "description": "The address the link was emailed to. Null for a copied link.", "type": "string" }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the partner opened the link." }, "last_viewed_at": { "nullable": true, "description": "When the partner last opened the link. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was issued." }, "url": { "type": "string", "description": "The address the partner opens. BrokerPlus keeps only a fingerprint of it, so this is the only time you can read it. Anybody who holds it sees the partner's hub." } }, "required": [ "object", "id", "hub_id", "channel", "recipient_email", "view_count", "last_viewed_at", "created_at", "url" ], "additionalProperties": false, "description": "The link that this call issued, with its address." } }, "required": [ "object", "id", "contact_id", "partner_name", "notify_stage_changes", "notify_funded", "show_funded", "show_not_proceeding", "revoked_at", "last_sent_at", "links", "created_at", "updated_at", "link" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-hubs/{id}": { "get": { "operationId": "getPartnerHub", "summary": "Retrieve a partner hub", "description": "One partner hub, with its settings and the links that still work. A link does not include its address: issue a new link to get one.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_hub", "description": "The type of this record. Always `partner_hub`.", "type": "string", "enum": [ "partner_hub" ] }, "id": { "type": "string", "description": "Stable identifier for the partner hub." }, "contact_id": { "type": "string", "description": "The partner's contact." }, "partner_name": { "type": "string", "description": "The partner's name, for display." }, "notify_stage_changes": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on moves to a new stage. Off until the broker turns it on." }, "notify_funded": { "type": "boolean", "description": "BrokerPlus emails the partner when a file they are on funds. Off until the broker turns it on." }, "show_funded": { "type": "boolean", "description": "The hub lists the files that funded. On until the broker turns it off. Open files are always listed." }, "show_not_proceeding": { "type": "boolean", "description": "The hub lists the files that ended without funding, such as cancelled or declined files. On until the broker turns it off. Open files are always listed." }, "revoked_at": { "nullable": true, "description": "When the broker turned the hub off. Every link then stops working. Null while the hub is on.", "type": "string" }, "last_sent_at": { "nullable": true, "description": "When the broker last emailed the hub to the partner. Null if never.", "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "partner_hub_link", "description": "The type of this record. Always `partner_hub_link`.", "type": "string", "enum": [ "partner_hub_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "hub_id": { "type": "string", "description": "The partner hub that the link opens." }, "channel": { "type": "string", "enum": [ "send", "copy", "notice" ], "description": "How the link left BrokerPlus: `send` in the broker's email to the partner, `copy` copied by the broker or issued through the API, `notice` in an update email to the partner." }, "recipient_email": { "nullable": true, "description": "The address the link was emailed to. Null for a copied link.", "type": "string" }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the partner opened the link." }, "last_viewed_at": { "nullable": true, "description": "When the partner last opened the link. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was issued." } }, "required": [ "object", "id", "hub_id", "channel", "recipient_email", "view_count", "last_viewed_at", "created_at" ], "additionalProperties": false }, "description": "The links that still work, newest first, at most 10. A link does not include its address: issue a new link with `POST /v1/partner-hubs/{id}/link` to get one." }, "created_at": { "type": "string", "description": "When the hub was opened." }, "updated_at": { "type": "string", "description": "When the hub settings last changed." } }, "required": [ "object", "id", "contact_id", "partner_name", "notify_stage_changes", "notify_funded", "show_funded", "show_not_proceeding", "revoked_at", "last_sent_at", "links", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/partner-hubs/{id}/link": { "post": { "operationId": "createPartnerHubLink", "summary": "Issue a partner hub link", "description": "Issues a new link to this partner hub and returns its address in `url`. BrokerPlus keeps only a fingerprint of a link, so a link issued before cannot be read back. Every link keeps working until the broker turns the hub off. If the hub is off, this turns it on again. BrokerPlus sends nothing: give the link to the partner yourself.", "tags": [ "Referral partners" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "partner_hub_link", "description": "The type of this record. Always `partner_hub_link`.", "type": "string", "enum": [ "partner_hub_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "hub_id": { "type": "string", "description": "The partner hub that the link opens." }, "channel": { "type": "string", "enum": [ "send", "copy", "notice" ], "description": "How the link left BrokerPlus: `send` in the broker's email to the partner, `copy` copied by the broker or issued through the API, `notice` in an update email to the partner." }, "recipient_email": { "nullable": true, "description": "The address the link was emailed to. Null for a copied link.", "type": "string" }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the partner opened the link." }, "last_viewed_at": { "nullable": true, "description": "When the partner last opened the link. Null if never.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was issued." }, "url": { "type": "string", "description": "The address the partner opens. BrokerPlus keeps only a fingerprint of it, so this is the only time you can read it. Anybody who holds it sees the partner's hub." } }, "required": [ "object", "id", "hub_id", "channel", "recipient_email", "view_count", "last_viewed_at", "created_at", "url" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The hub does not exist, or the broker cannot change its partner (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/offers": { "get": { "operationId": "listDealOffers", "summary": "List a deal's offers", "description": "The lender offers on the deal's offers tab, in the order the broker set. Rates are PERCENT (`4.79` means 4.79%).", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_offer", "description": "The type of this record. Always `deal_offer`.", "type": "string", "enum": [ "deal_offer" ] }, "id": { "type": "string", "description": "Stable identifier for the offer." }, "deal_id": { "type": "string", "description": "The deal the offer is on." }, "title": { "type": "string", "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "nullable": true, "description": "The lender, as the slug `GET /v1/lenders` uses. Null for a typed name.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, when the broker typed one.", "type": "string" }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "nullable": true, "description": "The mortgage amount, in dollars.", "type": "number" }, "rate": { "nullable": true, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "type": "number" }, "lump_sum_allowance_pct": { "nullable": true, "description": "The yearly lump-sum prepayment the offer allows, as a PERCENT of the mortgage, e.g. `15`.", "type": "number" }, "payment_increase_allowance_pct": { "nullable": true, "description": "The yearly payment increase the offer allows, as a PERCENT of the payment, e.g. `15`.", "type": "number" }, "pros": { "type": "array", "items": { "type": "string" }, "description": "What the broker likes about the offer." }, "cons": { "type": "array", "items": { "type": "string" }, "description": "What the broker does not like about the offer." }, "fee_collected_at": { "nullable": true, "description": "When the broker collected the fee on this offer. Null if not yet.", "type": "string" }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the offer on the deal. Lower comes first." }, "fees": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "offer_fee", "description": "The type of this record. Always `offer_fee`.", "type": "string", "enum": [ "offer_fee" ] }, "id": { "type": "string", "description": "Stable identifier for the fee." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "object", "id", "label", "kind", "amount", "s48_included", "broker_fee_financed", "broker_fee_paid_by_institution", "required_by_institution", "sort_order" ], "additionalProperties": false }, "description": "The fees on the offer, in order." }, "created_at": { "type": "string", "description": "When the offer was added." }, "updated_at": { "type": "string", "description": "When the offer last changed." } }, "required": [ "object", "id", "deal_id", "title", "lender_slug", "lender_name", "rate_type", "product_type", "term_months", "amortization_months", "payment_frequency", "mortgage_amount", "rate", "lump_sum_allowance_pct", "payment_increase_allowance_pct", "pros", "cons", "fee_collected_at", "sort_order", "fees", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealOffer", "summary": "Add an offer to a deal", "description": "Adds a lender offer to the deal's offers tab, with its fees. Send `rate` as a PERCENT. BrokerPlus sends nothing to the client.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "description": "The lender, as the slug `GET /v1/lenders` uses.", "nullable": true, "type": "string", "maxLength": 255 }, "lender_name": { "description": "The lender's name, for a lender with no slug.", "nullable": true, "type": "string", "maxLength": 255 }, "rate_type": { "description": "The rate type. `fixed` when you leave it out.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "description": "The mortgage amount, in dollars.", "nullable": true, "type": "number" }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "lump_sum_allowance_pct": { "description": "The yearly lump-sum prepayment allowed, as a PERCENT of the mortgage.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "payment_increase_allowance_pct": { "description": "The yearly payment increase allowed, as a PERCENT of the payment.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "pros": { "description": "What the broker likes about the offer.", "type": "array", "items": { "type": "string", "maxLength": 500 } }, "cons": { "description": "What the broker does not like about the offer.", "type": "array", "items": { "type": "string", "maxLength": 500 } }, "sort_order": { "description": "The position of the offer on the deal. Lower comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fees": { "description": "The fees on the offer. Replaces every fee when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "label", "amount" ], "additionalProperties": false } } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_offer", "description": "The type of this record. Always `deal_offer`.", "type": "string", "enum": [ "deal_offer" ] }, "id": { "type": "string", "description": "Stable identifier for the offer." }, "deal_id": { "type": "string", "description": "The deal the offer is on." }, "title": { "type": "string", "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "nullable": true, "description": "The lender, as the slug `GET /v1/lenders` uses. Null for a typed name.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, when the broker typed one.", "type": "string" }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "nullable": true, "description": "The mortgage amount, in dollars.", "type": "number" }, "rate": { "nullable": true, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "type": "number" }, "lump_sum_allowance_pct": { "nullable": true, "description": "The yearly lump-sum prepayment the offer allows, as a PERCENT of the mortgage, e.g. `15`.", "type": "number" }, "payment_increase_allowance_pct": { "nullable": true, "description": "The yearly payment increase the offer allows, as a PERCENT of the payment, e.g. `15`.", "type": "number" }, "pros": { "type": "array", "items": { "type": "string" }, "description": "What the broker likes about the offer." }, "cons": { "type": "array", "items": { "type": "string" }, "description": "What the broker does not like about the offer." }, "fee_collected_at": { "nullable": true, "description": "When the broker collected the fee on this offer. Null if not yet.", "type": "string" }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the offer on the deal. Lower comes first." }, "fees": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "offer_fee", "description": "The type of this record. Always `offer_fee`.", "type": "string", "enum": [ "offer_fee" ] }, "id": { "type": "string", "description": "Stable identifier for the fee." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "object", "id", "label", "kind", "amount", "s48_included", "broker_fee_financed", "broker_fee_paid_by_institution", "required_by_institution", "sort_order" ], "additionalProperties": false }, "description": "The fees on the offer, in order." }, "created_at": { "type": "string", "description": "When the offer was added." }, "updated_at": { "type": "string", "description": "When the offer last changed." } }, "required": [ "object", "id", "deal_id", "title", "lender_slug", "lender_name", "rate_type", "product_type", "term_months", "amortization_months", "payment_frequency", "mortgage_amount", "rate", "lump_sum_allowance_pct", "payment_increase_allowance_pct", "pros", "cons", "fee_collected_at", "sort_order", "fees", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/offers/compare": { "get": { "operationId": "getDealOfferComparison", "summary": "Compare a deal's offers", "description": "The offers tab's side-by-side comparison, worked out now: for each offer, the payment, mortgage default insurance, the penalty to break it, the fees and the APR; for each scenario, the mortgage it implies and the payment at each rate. Rates are PERCENT.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "offer_comparison", "description": "The type of this record. Always `offer_comparison`.", "type": "string", "enum": [ "offer_comparison" ] }, "deal_id": { "type": "string", "description": "The deal compared." }, "rates_fetched_at": { "nullable": true, "description": "When BrokerPlus last read the market rates.", "type": "string" }, "purchase_price": { "nullable": true, "description": "The price or value from the deal's application, in dollars.", "type": "number" }, "province": { "nullable": true, "description": "The province of the property, as a two-letter code.", "type": "string" }, "minimum_down_payment": { "nullable": true, "description": "The smallest down payment the price allows, in dollars.", "type": "number" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "offer_id": { "type": "string", "description": "The offer, from `GET /v1/deals/{id}/offers`." }, "monthly_payment": { "nullable": true, "description": "The monthly principal and interest, in dollars.", "type": "number" }, "payment": { "nullable": true, "description": "The payment at the offer's `payment_frequency`. Null when it has no frequency we price.", "type": "object", "properties": { "frequency": { "type": "string", "description": "The cadence: `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `accelerated_bi_weekly`, or `accelerated_weekly`." }, "amount": { "type": "number", "description": "The payment each period, in dollars." }, "payments_per_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many payments a year." }, "annual_outlay": { "type": "number", "description": "What the client pays in a year at this cadence, in dollars." } }, "required": [ "frequency", "amount", "payments_per_year", "annual_outlay" ], "additionalProperties": false }, "insurance": { "nullable": true, "description": "Default insurance. Null when the deal has no purchase price to measure against.", "type": "object", "properties": { "insured": { "type": "boolean", "description": "`true` when default insurance applies." }, "premium": { "type": "number", "description": "The insurance premium, in dollars. It is added to the mortgage." }, "premium_tax": { "type": "number", "description": "The provincial sales tax on the premium, in dollars. It is paid at closing." }, "premium_rate": { "type": "number", "description": "The premium as a PERCENT of the mortgage, e.g. `4` means 4%." }, "loan_to_value": { "type": "number", "description": "The loan-to-value ratio as a PERCENT, e.g. `90`." }, "financed_amount": { "type": "number", "description": "The mortgage with the premium added, in dollars." } }, "required": [ "insured", "premium", "premium_tax", "premium_rate", "loan_to_value", "financed_amount" ], "additionalProperties": false }, "penalty": { "nullable": true, "description": "An estimate of the penalty to break the mortgage. Null without a rate, an amount, and a term.", "type": "object", "properties": { "estimated": { "type": "number", "description": "The penalty to break the mortgage over the full term, in dollars." }, "interest_rate_differential": { "type": "number", "description": "The interest rate differential penalty, in dollars." }, "three_months_interest": { "type": "number", "description": "Three months of interest, in dollars." } }, "required": [ "estimated", "interest_rate_differential", "three_months_interest" ], "additionalProperties": false }, "lump_sum_interest_saved": { "nullable": true, "description": "Interest saved by using the yearly lump-sum allowance in full, in dollars.", "type": "number" }, "payment_increase_interest_saved": { "nullable": true, "description": "Interest saved by using the yearly payment increase in full, in dollars.", "type": "number" }, "fees_total": { "type": "number", "description": "Every fee on the offer, in dollars." }, "fees_due_on_closing": { "type": "number", "description": "The fees the client pays at closing, in dollars." }, "apr": { "nullable": true, "description": "The annual percentage rate (APR) as a PERCENT, e.g. `4.95`. Null when it cannot be worked out.", "type": "number" }, "cost_of_borrowing": { "nullable": true, "description": "The interest over the term plus the fees that count, in dollars.", "type": "number" } }, "required": [ "offer_id", "monthly_payment", "payment", "insurance", "penalty", "lump_sum_interest_saved", "payment_increase_interest_saved", "fees_total", "fees_due_on_closing", "apr", "cost_of_borrowing" ], "additionalProperties": false }, "description": "One entry for each offer, in the order of the offers." }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "scenario_id": { "type": "string", "description": "The scenario, from `GET /v1/deals/{id}/scenarios`." }, "mortgage_amount": { "nullable": true, "description": "The mortgage the scenario needs: the price less the down payment, in dollars.", "type": "number" }, "debt_payout_total": { "type": "number", "description": "The debts the scenario pays off, in dollars." }, "freed_monthly_cash_flow": { "type": "number", "description": "The monthly payments those debts no longer take, in dollars." }, "insurance": { "nullable": true, "description": "Default insurance. Null when the deal has no purchase price to measure against.", "type": "object", "properties": { "insured": { "type": "boolean", "description": "`true` when default insurance applies." }, "premium": { "type": "number", "description": "The insurance premium, in dollars. It is added to the mortgage." }, "premium_tax": { "type": "number", "description": "The provincial sales tax on the premium, in dollars. It is paid at closing." }, "premium_rate": { "type": "number", "description": "The premium as a PERCENT of the mortgage, e.g. `4` means 4%." }, "loan_to_value": { "type": "number", "description": "The loan-to-value ratio as a PERCENT, e.g. `90`." }, "financed_amount": { "type": "number", "description": "The mortgage with the premium added, in dollars." } }, "required": [ "insured", "premium", "premium_tax", "premium_rate", "loan_to_value", "financed_amount" ], "additionalProperties": false }, "closing_costs_total": { "nullable": true, "description": "The closing costs, with land transfer tax, in dollars.", "type": "number" }, "rate_options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The option's name." }, "rate": { "nullable": true, "description": "The rate as a PERCENT.", "type": "number" }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "monthly_payment": { "nullable": true, "description": "The monthly principal and interest, in dollars.", "type": "number" } }, "required": [ "label", "rate", "term_months", "monthly_payment" ], "additionalProperties": false }, "description": "The scenario priced at each of its rates." } }, "required": [ "scenario_id", "mortgage_amount", "debt_payout_total", "freed_monthly_cash_flow", "insurance", "closing_costs_total", "rate_options" ], "additionalProperties": false }, "description": "One entry for each scenario." } }, "required": [ "object", "deal_id", "rates_fetched_at", "purchase_price", "province", "minimum_down_payment", "offers", "scenarios" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/offers/{offerId}": { "get": { "operationId": "getDealOffer", "summary": "Retrieve a deal offer", "description": "One offer on the deal, with its fees.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "offerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_offer", "description": "The type of this record. Always `deal_offer`.", "type": "string", "enum": [ "deal_offer" ] }, "id": { "type": "string", "description": "Stable identifier for the offer." }, "deal_id": { "type": "string", "description": "The deal the offer is on." }, "title": { "type": "string", "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "nullable": true, "description": "The lender, as the slug `GET /v1/lenders` uses. Null for a typed name.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, when the broker typed one.", "type": "string" }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "nullable": true, "description": "The mortgage amount, in dollars.", "type": "number" }, "rate": { "nullable": true, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "type": "number" }, "lump_sum_allowance_pct": { "nullable": true, "description": "The yearly lump-sum prepayment the offer allows, as a PERCENT of the mortgage, e.g. `15`.", "type": "number" }, "payment_increase_allowance_pct": { "nullable": true, "description": "The yearly payment increase the offer allows, as a PERCENT of the payment, e.g. `15`.", "type": "number" }, "pros": { "type": "array", "items": { "type": "string" }, "description": "What the broker likes about the offer." }, "cons": { "type": "array", "items": { "type": "string" }, "description": "What the broker does not like about the offer." }, "fee_collected_at": { "nullable": true, "description": "When the broker collected the fee on this offer. Null if not yet.", "type": "string" }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the offer on the deal. Lower comes first." }, "fees": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "offer_fee", "description": "The type of this record. Always `offer_fee`.", "type": "string", "enum": [ "offer_fee" ] }, "id": { "type": "string", "description": "Stable identifier for the fee." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "object", "id", "label", "kind", "amount", "s48_included", "broker_fee_financed", "broker_fee_paid_by_institution", "required_by_institution", "sort_order" ], "additionalProperties": false }, "description": "The fees on the offer, in order." }, "created_at": { "type": "string", "description": "When the offer was added." }, "updated_at": { "type": "string", "description": "When the offer last changed." } }, "required": [ "object", "id", "deal_id", "title", "lender_slug", "lender_name", "rate_type", "product_type", "term_months", "amortization_months", "payment_frequency", "mortgage_amount", "rate", "lump_sum_allowance_pct", "payment_increase_allowance_pct", "pros", "cons", "fee_collected_at", "sort_order", "fees", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the offer does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealOffer", "summary": "Update a deal offer", "description": "Changes the fields you send and keeps the others. `fees` replaces every fee, so send each fee to keep.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "offerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "description": "The lender, as the slug `GET /v1/lenders` uses.", "nullable": true, "type": "string", "maxLength": 255 }, "lender_name": { "description": "The lender's name, for a lender with no slug.", "nullable": true, "type": "string", "maxLength": 255 }, "rate_type": { "description": "The rate type. `fixed` when you leave it out.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "description": "The mortgage amount, in dollars.", "nullable": true, "type": "number" }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "lump_sum_allowance_pct": { "description": "The yearly lump-sum prepayment allowed, as a PERCENT of the mortgage.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "payment_increase_allowance_pct": { "description": "The yearly payment increase allowed, as a PERCENT of the payment.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "pros": { "description": "What the broker likes about the offer.", "type": "array", "items": { "type": "string", "maxLength": 500 } }, "cons": { "description": "What the broker does not like about the offer.", "type": "array", "items": { "type": "string", "maxLength": 500 } }, "sort_order": { "description": "The position of the offer on the deal. Lower comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fees": { "description": "The fees on the offer. Replaces every fee when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "label", "amount" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_offer", "description": "The type of this record. Always `deal_offer`.", "type": "string", "enum": [ "deal_offer" ] }, "id": { "type": "string", "description": "Stable identifier for the offer." }, "deal_id": { "type": "string", "description": "The deal the offer is on." }, "title": { "type": "string", "description": "The offer's name, e.g. `First National 5-year fixed`." }, "lender_slug": { "nullable": true, "description": "The lender, as the slug `GET /v1/lenders` uses. Null for a typed name.", "type": "string" }, "lender_name": { "nullable": true, "description": "The lender's name, when the broker typed one.", "type": "string" }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment_frequency": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How often the payment is made, as payments a year: `12` monthly, `24` semi-monthly, `26` bi-weekly, `52` weekly. Also `1`, `2`, and `4`." }, "mortgage_amount": { "nullable": true, "description": "The mortgage amount, in dollars.", "type": "number" }, "rate": { "nullable": true, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction.", "type": "number" }, "lump_sum_allowance_pct": { "nullable": true, "description": "The yearly lump-sum prepayment the offer allows, as a PERCENT of the mortgage, e.g. `15`.", "type": "number" }, "payment_increase_allowance_pct": { "nullable": true, "description": "The yearly payment increase the offer allows, as a PERCENT of the payment, e.g. `15`.", "type": "number" }, "pros": { "type": "array", "items": { "type": "string" }, "description": "What the broker likes about the offer." }, "cons": { "type": "array", "items": { "type": "string" }, "description": "What the broker does not like about the offer." }, "fee_collected_at": { "nullable": true, "description": "When the broker collected the fee on this offer. Null if not yet.", "type": "string" }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the offer on the deal. Lower comes first." }, "fees": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "offer_fee", "description": "The type of this record. Always `offer_fee`.", "type": "string", "enum": [ "offer_fee" ] }, "id": { "type": "string", "description": "Stable identifier for the fee." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "What the fee is, e.g. `Appraisal`." }, "kind": { "nullable": true, "description": "The kind of fee, e.g. `appraisal`, `legal`, or `broker`.", "type": "string", "maxLength": 120 }, "amount": { "type": "number", "description": "The fee, in dollars." }, "s48_included": { "type": "boolean", "description": "`true` when the fee counts in the cost of borrowing, so it enters the annual percentage rate (APR)." }, "broker_fee_financed": { "type": "boolean", "description": "For a broker fee, `true` when it is added to the mortgage." }, "broker_fee_paid_by_institution": { "type": "boolean", "description": "For a broker fee, `true` when the lender pays it to the broker." }, "required_by_institution": { "type": "boolean", "description": "`true` when the lender requires the fee, e.g. an appraisal the lender asked for." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the fee in the list. Lower comes first." } }, "required": [ "object", "id", "label", "kind", "amount", "s48_included", "broker_fee_financed", "broker_fee_paid_by_institution", "required_by_institution", "sort_order" ], "additionalProperties": false }, "description": "The fees on the offer, in order." }, "created_at": { "type": "string", "description": "When the offer was added." }, "updated_at": { "type": "string", "description": "When the offer last changed." } }, "required": [ "object", "id", "deal_id", "title", "lender_slug", "lender_name", "rate_type", "product_type", "term_months", "amortization_months", "payment_frequency", "mortgage_amount", "rate", "lump_sum_allowance_pct", "payment_increase_allowance_pct", "pros", "cons", "fee_collected_at", "sort_order", "fees", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the offer does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealOffer", "summary": "Delete a deal offer", "description": "Removes the offer and its fees from the deal.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "offerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the offer does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/scenarios": { "get": { "operationId": "listDealScenarios", "summary": "List a deal's scenarios", "description": "The what-if scenarios on the deal: a property sold, debts paid out, and the rates to try. Rates are PERCENT.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_scenario", "description": "The type of this record. Always `deal_scenario`.", "type": "string", "enum": [ "deal_scenario" ] }, "id": { "type": "string", "description": "Stable identifier for the scenario." }, "deal_id": { "type": "string", "description": "The deal the scenario is on." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "down_payment": { "nullable": true, "description": "The down payment, in dollars.", "type": "number" }, "down_payment_source": { "nullable": true, "description": "Where the down payment comes from.", "type": "string" }, "sales_proceeds": { "nullable": true, "description": "The money from a sale that goes into the file, in dollars.", "type": "number" }, "debt_payouts": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false }, "description": "The debts the scenario looks at." }, "rate_options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false }, "description": "The rates the scenario is priced at." }, "dispositions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false }, "description": "The properties the client sells." }, "sale_costs": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false }, "description": "The costs of each sale." }, "allocation": { "type": "object", "properties": { "to_mortgage": { "nullable": true, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "type": "array", "items": { "type": "string" }, "description": "The debts the sales pay off." }, "to_down_payment": { "nullable": true, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "nullable": true, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false, "description": "Where the money from the sales goes." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the scenario on the deal. Lower comes first." }, "created_at": { "type": "string", "description": "When the scenario was added." }, "updated_at": { "type": "string", "description": "When the scenario last changed." } }, "required": [ "object", "id", "deal_id", "name", "product_type", "amortization_months", "down_payment", "down_payment_source", "sales_proceeds", "debt_payouts", "rate_options", "dispositions", "sale_costs", "allocation", "sort_order", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealScenario", "summary": "Add a scenario to a deal", "description": "Adds a what-if scenario to the deal. The comparison prices it at each rate in `rate_options`. BrokerPlus sends nothing to the client.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "down_payment": { "description": "The down payment, in dollars.", "nullable": true, "type": "number" }, "down_payment_source": { "description": "Where the down payment comes from, e.g. `savings` or `gift`.", "nullable": true, "type": "string", "maxLength": 255 }, "sales_proceeds": { "description": "The money from a sale that goes into the file, in dollars.", "nullable": true, "type": "number" }, "debt_payouts": { "description": "The debts the scenario looks at. Replaces the list when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false } }, "rate_options": { "description": "The rates to price the scenario at. Replaces the list when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false } }, "dispositions": { "description": "The properties the client sells to fund the file. Replaces the list when sent.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false } }, "sale_costs": { "description": "The costs of each sale. Replaces the list when sent.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false } }, "allocation": { "description": "Where the money from the sales goes.", "type": "object", "properties": { "to_mortgage": { "default": 0, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "default": [], "description": "The debts the sales pay off.", "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "to_down_payment": { "default": 0, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "default": 0, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false }, "sort_order": { "description": "The position of the scenario on the deal. Lower comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_scenario", "description": "The type of this record. Always `deal_scenario`.", "type": "string", "enum": [ "deal_scenario" ] }, "id": { "type": "string", "description": "Stable identifier for the scenario." }, "deal_id": { "type": "string", "description": "The deal the scenario is on." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "down_payment": { "nullable": true, "description": "The down payment, in dollars.", "type": "number" }, "down_payment_source": { "nullable": true, "description": "Where the down payment comes from.", "type": "string" }, "sales_proceeds": { "nullable": true, "description": "The money from a sale that goes into the file, in dollars.", "type": "number" }, "debt_payouts": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false }, "description": "The debts the scenario looks at." }, "rate_options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false }, "description": "The rates the scenario is priced at." }, "dispositions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false }, "description": "The properties the client sells." }, "sale_costs": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false }, "description": "The costs of each sale." }, "allocation": { "type": "object", "properties": { "to_mortgage": { "nullable": true, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "type": "array", "items": { "type": "string" }, "description": "The debts the sales pay off." }, "to_down_payment": { "nullable": true, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "nullable": true, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false, "description": "Where the money from the sales goes." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the scenario on the deal. Lower comes first." }, "created_at": { "type": "string", "description": "When the scenario was added." }, "updated_at": { "type": "string", "description": "When the scenario last changed." } }, "required": [ "object", "id", "deal_id", "name", "product_type", "amortization_months", "down_payment", "down_payment_source", "sales_proceeds", "debt_payouts", "rate_options", "dispositions", "sale_costs", "allocation", "sort_order", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/scenarios/{scenarioId}": { "get": { "operationId": "getDealScenario", "summary": "Retrieve a deal scenario", "description": "One scenario on the deal.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "scenarioId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_scenario", "description": "The type of this record. Always `deal_scenario`.", "type": "string", "enum": [ "deal_scenario" ] }, "id": { "type": "string", "description": "Stable identifier for the scenario." }, "deal_id": { "type": "string", "description": "The deal the scenario is on." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "down_payment": { "nullable": true, "description": "The down payment, in dollars.", "type": "number" }, "down_payment_source": { "nullable": true, "description": "Where the down payment comes from.", "type": "string" }, "sales_proceeds": { "nullable": true, "description": "The money from a sale that goes into the file, in dollars.", "type": "number" }, "debt_payouts": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false }, "description": "The debts the scenario looks at." }, "rate_options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false }, "description": "The rates the scenario is priced at." }, "dispositions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false }, "description": "The properties the client sells." }, "sale_costs": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false }, "description": "The costs of each sale." }, "allocation": { "type": "object", "properties": { "to_mortgage": { "nullable": true, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "type": "array", "items": { "type": "string" }, "description": "The debts the sales pay off." }, "to_down_payment": { "nullable": true, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "nullable": true, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false, "description": "Where the money from the sales goes." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the scenario on the deal. Lower comes first." }, "created_at": { "type": "string", "description": "When the scenario was added." }, "updated_at": { "type": "string", "description": "When the scenario last changed." } }, "required": [ "object", "id", "deal_id", "name", "product_type", "amortization_months", "down_payment", "down_payment_source", "sales_proceeds", "debt_payouts", "rate_options", "dispositions", "sale_costs", "allocation", "sort_order", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the scenario does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealScenario", "summary": "Update a deal scenario", "description": "Changes the fields you send and keeps the others. A list you send replaces the stored list.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "scenarioId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "down_payment": { "description": "The down payment, in dollars.", "nullable": true, "type": "number" }, "down_payment_source": { "description": "Where the down payment comes from, e.g. `savings` or `gift`.", "nullable": true, "type": "string", "maxLength": 255 }, "sales_proceeds": { "description": "The money from a sale that goes into the file, in dollars.", "nullable": true, "type": "number" }, "debt_payouts": { "description": "The debts the scenario looks at. Replaces the list when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false } }, "rate_options": { "description": "The rates to price the scenario at. Replaces the list when sent.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false } }, "dispositions": { "description": "The properties the client sells to fund the file. Replaces the list when sent.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false } }, "sale_costs": { "description": "The costs of each sale. Replaces the list when sent.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false } }, "allocation": { "description": "Where the money from the sales goes.", "type": "object", "properties": { "to_mortgage": { "default": 0, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "default": [], "description": "The debts the sales pay off.", "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "to_down_payment": { "default": 0, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "default": 0, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false }, "sort_order": { "description": "The position of the scenario on the deal. Lower comes first.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_scenario", "description": "The type of this record. Always `deal_scenario`.", "type": "string", "enum": [ "deal_scenario" ] }, "id": { "type": "string", "description": "Stable identifier for the scenario." }, "deal_id": { "type": "string", "description": "The deal the scenario is on." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The scenario's name, e.g. `Sell the rental`." }, "product_type": { "type": "string", "enum": [ "insured", "conventional", "insurable" ], "description": "`insured` is default-insured with less than 20% down, `conventional` has 20% or more down and no insurance, and `insurable` qualifies for insurance the lender buys." }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "down_payment": { "nullable": true, "description": "The down payment, in dollars.", "type": "number" }, "down_payment_source": { "nullable": true, "description": "Where the down payment comes from.", "type": "string" }, "sales_proceeds": { "nullable": true, "description": "The money from a sale that goes into the file, in dollars.", "type": "number" }, "debt_payouts": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The debt, e.g. `Visa`." }, "balance": { "type": "number", "description": "The balance, in dollars." }, "monthly_payment": { "description": "The monthly payment, in dollars.", "nullable": true, "type": "number" }, "payoff": { "description": "`true` when the scenario pays the debt off.", "type": "boolean" } }, "required": [ "label", "balance" ], "additionalProperties": false }, "description": "The debts the scenario looks at." }, "rate_options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The option's name, e.g. `5-year fixed`." }, "rate_type": { "description": "The rate type.", "type": "string", "enum": [ "fixed", "variable", "adjustable" ] }, "rate": { "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%.", "nullable": true, "type": "number", "minimum": 0, "maximum": 30 }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label" ], "additionalProperties": false }, "description": "The rates the scenario is priced at." }, "dispositions": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The sale's id inside the scenario. You choose it." }, "property_id": { "description": "The other property sold, from `GET /v1/deals/{id}/other-properties`. Null for the deal's own property.", "nullable": true, "type": "string", "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The property sold, for display." }, "sale_price": { "type": "number", "description": "The sale price, in dollars." }, "mortgage_balance": { "description": "The mortgage on the property, in dollars.", "type": "number" }, "liability_ids": { "default": [], "description": "The debts secured on the property, paid out from the sale.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "label", "sale_price", "liability_ids" ], "additionalProperties": false }, "description": "The properties the client sells." }, "sale_costs": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "disposition_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The `id` of the sale in `dispositions`." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cost, for display." }, "kind": { "type": "string", "enum": [ "commission", "legal", "discharge", "penalty", "tax_adjustment", "other" ], "description": "The kind of cost." }, "amount": { "type": "number", "description": "The cost, in dollars." }, "pct": { "description": "For a commission, the PERCENT of the sale price the broker typed. `amount` is what counts.", "nullable": true, "type": "number" } }, "required": [ "disposition_id", "label", "kind", "amount" ], "additionalProperties": false }, "description": "The costs of each sale." }, "allocation": { "type": "object", "properties": { "to_mortgage": { "nullable": true, "description": "Dollars from the sales that pay down the mortgage.", "type": "number" }, "to_debts": { "type": "array", "items": { "type": "string" }, "description": "The debts the sales pay off." }, "to_down_payment": { "nullable": true, "description": "Dollars from the sales that go to the down payment.", "type": "number" }, "to_cash": { "nullable": true, "description": "Dollars from the sales that the client keeps.", "type": "number" } }, "required": [ "to_mortgage", "to_debts", "to_down_payment", "to_cash" ], "additionalProperties": false, "description": "Where the money from the sales goes." }, "sort_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The position of the scenario on the deal. Lower comes first." }, "created_at": { "type": "string", "description": "When the scenario was added." }, "updated_at": { "type": "string", "description": "When the scenario last changed." } }, "required": [ "object", "id", "deal_id", "name", "product_type", "amortization_months", "down_payment", "down_payment_source", "sales_proceeds", "debt_payouts", "rate_options", "dispositions", "sale_costs", "allocation", "sort_order", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the scenario does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteDealScenario", "summary": "Delete a deal scenario", "description": "Removes the scenario from the deal.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "scenarioId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the scenario does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/strategy-analyses": { "get": { "operationId": "listStrategyAnalyses", "summary": "List strategy analyses", "description": "The strategy analyses the broker built, most recently changed first. An analysis compares up to 8 mortgage options for a client against one of them. Use `deal_id` for the analyses on one deal.", "tags": [ "Planning" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the analyses on this deal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "strategy_analysis", "description": "The type of this record. Always `strategy_analysis`.", "type": "string", "enum": [ "strategy_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false }, "description": "The options compared. At most 8." }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false, "description": "The note that explains the recommendation to the client." }, "user_id": { "nullable": true, "description": "The broker who made the analysis. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the analysis was made." }, "updated_at": { "type": "string", "description": "When the analysis last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "match_payment", "target_payment", "baseline_index", "options", "client_intent", "deal_defender", "user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createStrategyAnalysis", "summary": "Create a strategy analysis", "description": "Saves a strategy analysis, as the strategy board in BrokerPlus saves one. Send each option's `rate` as a percent. The broker opens it on the board. BrokerPlus sends nothing to the client.", "tags": [ "Planning" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "default": false, "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "default": [], "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false }, "description": "The options compared. At most 8." }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false, "description": "The note that explains the recommendation to the client." } }, "required": [ "title", "match_payment", "baseline_index", "options" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "strategy_analysis", "description": "The type of this record. Always `strategy_analysis`.", "type": "string", "enum": [ "strategy_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false }, "description": "The options compared. At most 8." }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false, "description": "The note that explains the recommendation to the client." }, "user_id": { "nullable": true, "description": "The broker who made the analysis. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the analysis was made." }, "updated_at": { "type": "string", "description": "When the analysis last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "match_payment", "target_payment", "baseline_index", "options", "client_intent", "deal_defender", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "`deal_id` names a deal the broker cannot read (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/strategy-analyses/{id}": { "get": { "operationId": "getStrategyAnalysis", "summary": "Retrieve a strategy analysis", "description": "One strategy analysis, with every option. Rates are PERCENT (`4.79` means 4.79%).", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "strategy_analysis", "description": "The type of this record. Always `strategy_analysis`.", "type": "string", "enum": [ "strategy_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false }, "description": "The options compared. At most 8." }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false, "description": "The note that explains the recommendation to the client." }, "user_id": { "nullable": true, "description": "The broker who made the analysis. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the analysis was made." }, "updated_at": { "type": "string", "description": "When the analysis last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "match_payment", "target_payment", "baseline_index", "options", "client_intent", "deal_defender", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No analysis the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateStrategyAnalysis", "summary": "Update a strategy analysis", "description": "Changes the fields you send and keeps the others. `options` replaces every option, so send each option to keep.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "description": "Replaces every option when sent.", "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false } }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "description": "Replaces the note when sent.", "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "strategy_analysis", "description": "The type of this record. Always `strategy_analysis`.", "type": "string", "enum": [ "strategy_analysis" ] }, "id": { "type": "string", "description": "Stable identifier for the analysis." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The analysis's name." }, "client_name": { "nullable": true, "description": "The client's name as the report prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the analysis is on. Null when it is on no deal.", "type": "string" }, "match_payment": { "type": "boolean", "description": "`true` when every option is priced at the same payment." }, "target_payment": { "nullable": true, "description": "The monthly payment to match, in dollars, when `match_payment` is `true`.", "type": "number", "minimum": 0, "exclusiveMinimum": true }, "baseline_index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The position in `options` of the option the others are measured against. `0` is the first." }, "options": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The option's id inside the analysis. You choose it.", "type": "string", "maxLength": 64 }, "label": { "default": "", "description": "The option's heading, e.g. `Stay with TD`.", "type": "string", "maxLength": 120 }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "nullable": true, "type": "string", "maxLength": 120 }, "balance": { "type": "number", "minimum": 0, "description": "The mortgage balance, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization, in months." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months." }, "compounding": { "default": "semi_annual", "description": "How often interest compounds. A Canadian fixed rate compounds `semi_annual`.", "type": "string", "enum": [ "semi_annual", "monthly" ] }, "payment_frequency": { "default": "monthly", "description": "How often the payment is made, e.g. `monthly` or `accelerated_bi_weekly`.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "configured": { "description": "`false` for an option the broker added and has not filled in yet. Its results stay empty.", "type": "boolean" }, "payment_override": { "description": "A monthly payment the broker set for this option, in dollars. Null uses the payment worked out.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "product_notes": { "description": "What the broker read off the commitment letter, keyed by topic, e.g. `portability`.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 } }, "readvanceable": { "description": "For a readvanceable mortgage, the line of credit that shares its charge. Null for a plain mortgage.", "nullable": true, "type": "object", "properties": { "home_value": { "type": "number", "minimum": 0, "description": "The value of the home, in dollars." }, "limit": { "type": "number", "minimum": 0, "maximum": 100, "description": "The borrowing limit as a PERCENT of the home value, e.g. `80`." }, "heloc_balance": { "type": "number", "minimum": 0, "description": "The balance on the line of credit, in dollars." }, "heloc_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate on the line of credit as a PERCENT." } }, "required": [ "home_value", "limit", "heloc_balance", "heloc_rate" ], "additionalProperties": false } }, "required": [ "label", "balance", "rate", "amortization_months", "term_months", "compounding", "payment_frequency" ], "additionalProperties": false }, "description": "The options compared. At most 8." }, "client_intent": { "nullable": true, "type": "object", "properties": { "horizon": { "description": "What the client expects to do: keep the mortgage `to_maturity`, or they `may_move` or `may_refinance`.", "nullable": true, "type": "string", "enum": [ "to_maturity", "may_move", "may_refinance" ] }, "needs_equity_access": { "default": false, "description": "`true` when the client needs to borrow against the home.", "type": "boolean" } }, "required": [ "needs_equity_access" ], "additionalProperties": false, "description": "What the client plans. It decides which product terms the note leads with." }, "deal_defender": { "nullable": true, "type": "object", "properties": { "sections": { "default": [], "description": "The sections the broker kept.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "bottom_line", "vs_baseline", "deal_strength", "tradeoffs" ], "description": "The part of the note the section is." }, "prose": { "type": "string", "maxLength": 8000, "description": "The section as the client reads it." }, "original_prose": { "default": "", "description": "The section as BrokerPlus wrote it.", "type": "string", "maxLength": 8000 }, "annotations": { "default": [], "description": "The notes that back up the section.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "excerpt": { "type": "string", "maxLength": 2000, "description": "The words in `prose` the note is about." }, "title": { "type": "string", "maxLength": 200, "description": "The note's heading." }, "kind": { "type": "string", "enum": [ "calculated", "lender_document", "broker_stated" ], "description": "Where the fact comes from: worked out, a lender document, or the broker." }, "detail": { "type": "string", "maxLength": 4000, "description": "The note." }, "source": { "description": "The document the fact comes from.", "nullable": true, "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "The address of the source." }, "quote": { "description": "The words quoted from it.", "nullable": true, "type": "string", "maxLength": 4000 }, "label": { "description": "The name of the source.", "nullable": true, "type": "string", "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "excerpt", "title", "kind", "detail" ], "additionalProperties": false } } }, "required": [ "group", "prose", "original_prose", "annotations" ], "additionalProperties": false } }, "generated_at": { "default": null, "description": "When BrokerPlus wrote the note. Null if never.", "nullable": true, "type": "string" } }, "required": [ "sections", "generated_at" ], "additionalProperties": false, "description": "The note that explains the recommendation to the client." }, "user_id": { "nullable": true, "description": "The broker who made the analysis. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the analysis was made." }, "updated_at": { "type": "string", "description": "When the analysis last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "match_payment", "target_payment", "baseline_index", "options", "client_intent", "deal_defender", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The analysis or the deal does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteStrategyAnalysis", "summary": "Delete a strategy analysis", "description": "Deletes the analysis.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No analysis the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/mortgage-plans": { "get": { "operationId": "listMortgagePlans", "summary": "List mortgage plans", "description": "The mortgage plans the broker built, most recently changed first. A plan shows a client up to 3 options side by side, each with its payment, its monthly housing costs, and the cash to close. Use `deal_id` or `contact_id` for the plans on one deal or for one person.", "tags": [ "Planning" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the plans on this deal." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the plans for this contact." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "mortgage_plan", "description": "The type of this record. Always `mortgage_plan`.", "type": "string", "enum": [ "mortgage_plan" ] }, "id": { "type": "string", "description": "Stable identifier for the plan." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false }, "description": "The options, side by side. At most 3." }, "refinance": { "nullable": true, "description": "The client's mortgage today. Only for a refinance.", "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false }, "user_id": { "nullable": true, "description": "The broker who made the plan. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the plan was made." }, "updated_at": { "type": "string", "description": "When the plan last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "contact_id", "plan_type", "province", "dwelling", "first_time_buyer", "municipality", "notes", "columns", "refinance", "user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createMortgagePlan", "summary": "Create a mortgage plan", "description": "Saves a mortgage plan, as the plan builder in BrokerPlus saves one. Put it on a deal with `deal_id`, on a person with `contact_id`, or on both when the two are on the same team. The broker opens it in the plan builder. BrokerPlus sends nothing to the client.", "tags": [ "Planning" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "default": false, "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false }, "description": "The options, side by side. At most 3." }, "refinance": { "nullable": true, "description": "The client's mortgage today. Only for a refinance.", "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false } }, "required": [ "title", "plan_type", "province", "dwelling", "first_time_buyer", "columns" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "mortgage_plan", "description": "The type of this record. Always `mortgage_plan`.", "type": "string", "enum": [ "mortgage_plan" ] }, "id": { "type": "string", "description": "Stable identifier for the plan." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false }, "description": "The options, side by side. At most 3." }, "refinance": { "nullable": true, "description": "The client's mortgage today. Only for a refinance.", "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false }, "user_id": { "nullable": true, "description": "The broker who made the plan. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the plan was made." }, "updated_at": { "type": "string", "description": "When the plan last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "contact_id", "plan_type", "province", "dwelling", "first_time_buyer", "municipality", "notes", "columns", "refinance", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the contact does not exist, the broker cannot read it, or the two are on different teams (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/mortgage-plans/{id}": { "get": { "operationId": "getMortgagePlan", "summary": "Retrieve a mortgage plan", "description": "One mortgage plan, with every option in it. Rates are PERCENT (`4.79` means 4.79%).", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "mortgage_plan", "description": "The type of this record. Always `mortgage_plan`.", "type": "string", "enum": [ "mortgage_plan" ] }, "id": { "type": "string", "description": "Stable identifier for the plan." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false }, "description": "The options, side by side. At most 3." }, "refinance": { "nullable": true, "description": "The client's mortgage today. Only for a refinance.", "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false }, "user_id": { "nullable": true, "description": "The broker who made the plan. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the plan was made." }, "updated_at": { "type": "string", "description": "When the plan last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "contact_id", "plan_type", "province", "dwelling", "first_time_buyer", "municipality", "notes", "columns", "refinance", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateMortgagePlan", "summary": "Update a mortgage plan", "description": "Changes a mortgage plan. Send only the fields to change. `columns` replaces every option, so send each option you want to keep.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "description": "Replaces every option when sent.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false } }, "refinance": { "description": "Replaces the refinance figures when sent. Null clears them.", "nullable": true, "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "mortgage_plan", "description": "The type of this record. Always `mortgage_plan`.", "type": "string", "enum": [ "mortgage_plan" ] }, "id": { "type": "string", "description": "Stable identifier for the plan." }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The plan's name, for example `Smith purchase options`." }, "client_name": { "nullable": true, "description": "The client's name as the plan prints it.", "type": "string", "maxLength": 160 }, "deal_id": { "nullable": true, "description": "The deal the plan is on. Null when it is on no deal.", "type": "string" }, "contact_id": { "nullable": true, "description": "The contact the plan is for. Null when it is for no contact.", "type": "string" }, "plan_type": { "type": "string", "enum": [ "purchase_high_ratio", "purchase_conventional", "sale_and_purchase", "refinance" ], "description": "What the plan is for: a purchase with less than 20% down (`purchase_high_ratio`), a purchase with 20% or more down (`purchase_conventional`), selling one home to buy another (`sale_and_purchase`), or `refinance`." }, "province": { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "ON", "PE", "QC", "SK", "NT", "NU", "YT" ], "description": "The province of the home, as a two-letter code, e.g. `ON`." }, "dwelling": { "type": "string", "enum": [ "freehold", "condo" ], "description": "The kind of home. It sets the default housing costs." }, "first_time_buyer": { "type": "boolean", "description": "`true` when the client buys a home for the first time." }, "municipality": { "nullable": true, "description": "The city or town, for the land transfer tax.", "type": "string", "maxLength": 120 }, "notes": { "nullable": true, "description": "The broker's notes on the plan.", "type": "string", "maxLength": 5000 }, "columns": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64, "description": "The option's id inside the plan. You choose it, for example `a`." }, "label": { "default": "", "description": "The option's heading, for example `5-year fixed`.", "type": "string", "maxLength": 120 }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The mortgage rate as a PERCENT, e.g. `4.79` means 4.79%. Not a fraction." }, "rate_type": { "type": "string", "enum": [ "fixed", "variable", "adjustable" ], "description": "The rate type." }, "term_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The term, in months. `60` is a 5-year term." }, "amortization_years": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 50, "description": "The amortization, in years." }, "budget": { "default": {}, "description": "The monthly housing costs the broker set. A cost you leave out uses the default that its description names.", "type": "object", "properties": { "property_tax": { "description": "Property tax, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "condo_fees": { "description": "Condo fees, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "home_insurance": { "description": "Home insurance, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "utilities": { "description": "Utilities, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "communications": { "description": "Phone and internet, in dollars a month. Null uses the provincial average.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 }, "other": { "description": "Other housing costs, in dollars a month. Null leaves it at 0.", "nullable": true, "type": "number", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "lender": { "description": "The lender, for display.", "type": "string", "maxLength": 120 }, "product": { "description": "The lender's product, for display.", "type": "string", "maxLength": 120 }, "purchase_price": { "type": "number", "minimum": 0, "description": "The purchase price, in dollars." }, "down_payment": { "type": "number", "minimum": 0, "description": "The down payment, in dollars." }, "non_traditional_down_payment": { "description": "`true` when the down payment is borrowed or from another non-traditional source.", "type": "boolean" }, "sale_price": { "type": "number", "minimum": 0, "description": "The sale price of the home the client sells, in dollars." }, "existing_mortgage_payout": { "type": "number", "minimum": 0, "description": "The mortgage paid out on the home the client sells, in dollars." }, "realtor_fee_pct": { "description": "The realtor fee on the sale as a PERCENT of the sale price, e.g. `5` means 5%.", "type": "number", "minimum": 0, "maximum": 100 }, "selling_costs": { "type": "number", "minimum": 0, "description": "Other costs of the sale, in dollars." }, "current_balance": { "type": "number", "minimum": 0, "description": "For a refinance, the balance of the mortgage today, in dollars." }, "new_money": { "type": "number", "minimum": 0, "description": "For a refinance, the extra money the client takes out, in dollars." }, "property_value": { "type": "number", "minimum": 0, "description": "For a refinance, the value of the property, in dollars." }, "rolled_fees": { "type": "number", "minimum": 0, "description": "For a refinance, the fees added to the new mortgage, in dollars." }, "selected_debt_ids": { "description": "For a refinance, the `id` of each debt in `refinance.debts` that this option pays off.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "finance_penalty": { "description": "For a refinance, `true` when the penalty to break the mortgage is added to the new mortgage.", "type": "boolean" }, "closing_costs": { "description": "The closing costs, in dollars. Null uses 1.5% of the purchase price.", "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "id", "label", "rate", "rate_type", "term_months", "amortization_years", "budget" ], "additionalProperties": false }, "description": "The options, side by side. At most 3." }, "refinance": { "nullable": true, "description": "The client's mortgage today. Only for a refinance.", "type": "object", "properties": { "source": { "description": "Where the broker copied the figures from. Leave it out for figures you type.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deal", "contact" ], "description": "The kind of record the figures came from." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The id of that deal or contact." }, "label": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The name of that record, for display." }, "refreshed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figures were copied from it." } }, "required": [ "kind", "id", "label", "refreshed_at" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance of the mortgage today, in dollars." }, "payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment today, in dollars." }, "rate": { "type": "number", "minimum": 0, "maximum": 30, "description": "The rate today as a PERCENT, e.g. `5.49` means 5.49%." }, "amortization_months": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 600, "description": "The amortization left, in months." }, "property_value": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The value of the property, in dollars." }, "penalty": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "The penalty to break the mortgage, in dollars." }, "lender_name": { "description": "The lender today.", "nullable": true, "type": "string", "maxLength": 160 }, "product_name": { "description": "The product today.", "nullable": true, "type": "string", "maxLength": 160 }, "penalty_method": { "description": "How the penalty was worked out.", "nullable": true, "type": "string", "maxLength": 80 }, "penalty_calculated_at": { "description": "When the penalty was worked out.", "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "balance", "payment", "rate", "amortization_months", "property_value", "penalty" ], "additionalProperties": false, "description": "The mortgage the client has today." }, "debts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The debt's id inside the plan." }, "source": { "type": "string", "enum": [ "profile", "manual" ], "description": "`profile` when copied from the client's debts, `manual` when typed." }, "debt_type": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The kind of debt, e.g. `credit_card`." }, "creditor_name": { "description": "Who the client owes.", "nullable": true, "type": "string", "maxLength": 160 }, "balance": { "type": "number", "minimum": 0, "maximum": 100000000, "description": "The balance, in dollars." }, "interest_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `19.99` means 19.99%." }, "monthly_payment": { "type": "number", "minimum": 0, "maximum": 1000000, "description": "The monthly payment, in dollars." } }, "required": [ "id", "source", "debt_type", "balance", "interest_rate", "monthly_payment" ], "additionalProperties": false }, "description": "The client's other debts that a refinance can pay off." } }, "required": [ "current", "debts" ], "additionalProperties": false }, "user_id": { "nullable": true, "description": "The broker who made the plan. Resolve it with `GET /v1/users`.", "type": "string" }, "created_at": { "type": "string", "description": "When the plan was made." }, "updated_at": { "type": "string", "description": "When the plan last changed." } }, "required": [ "object", "id", "title", "client_name", "deal_id", "contact_id", "plan_type", "province", "dwelling", "first_time_buyer", "municipality", "notes", "columns", "refinance", "user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The plan, the deal, or the contact does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteMortgagePlan", "summary": "Delete a mortgage plan", "description": "Deletes a mortgage plan. The deal and the contact stay.", "tags": [ "Planning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/nps-alert-rules": { "get": { "operationId": "listNpsAlertRules", "summary": "List NPS alert rules", "description": "The brokerage's alert rules for Net Promoter Score (NPS) answers, in their order. When a client answers a survey, every active rule whose score range holds the score runs: it alerts brokers and can add a task. Ranges can overlap. A brokerage with no rules gets the three starter rules from BrokerPlus on the first read.", "tags": [ "Client surveys" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "nps_alert_rule", "description": "The type of this record. Always `nps_alert_rule`.", "type": "string", "enum": [ "nps_alert_rule" ] }, "id": { "type": "string", "description": "Stable identifier for the alert rule." }, "name": { "type": "string", "description": "The brokerage's name for the score range, for example `Unhappy client`. It starts each alert." }, "min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The lowest score the rule matches, from 0 to 10. The range includes it." }, "max_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The highest score the rule matches, from 0 to 10. The range includes it." }, "notify_owner": { "type": "boolean", "description": "True alerts the broker who sent the survey, in addition to the brokers in `broker_ids`." }, "broker_ids": { "type": "array", "items": { "type": "string" }, "description": "More brokers to alert. Resolve each with `GET /v1/users`." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. An alert always goes in the app." }, "task_title": { "nullable": true, "description": "The title of the task the rule adds on the client's contact. Null adds no task.", "type": "string" }, "task_body": { "nullable": true, "description": "The details of that task.", "type": "string" }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task. Null gives it to the broker who sent the survey.", "type": "string" }, "task_due_in_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The days from the answer until the task is due." }, "is_active": { "type": "boolean", "description": "False keeps the rule but stops it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the rule in the list. Every rule that matches runs." }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "When the rule last changed." } }, "required": [ "object", "id", "name", "min_score", "max_score", "notify_owner", "broker_ids", "channels", "task_title", "task_body", "task_assignee_user_id", "task_due_in_days", "is_active", "position", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createNpsAlertRule", "summary": "Create an NPS alert rule", "description": "Adds an alert rule at the end of the list. Only `name`, `min_score`, and `max_score` are required. The rule alerts brokers in the brokerage only.", "tags": [ "Client surveys" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The name for the score range. 120 characters at most." }, "min_score": { "type": "integer", "minimum": 0, "maximum": 10, "description": "The lowest score the rule matches, from 0 to 10." }, "max_score": { "type": "integer", "minimum": 0, "maximum": 10, "description": "The highest score the rule matches, from 0 to 10. It must not be below `min_score`." }, "notify_owner": { "type": "boolean", "description": "Alert the broker who sent the survey. Defaults to true." }, "broker_ids": { "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "More brokers to alert, from `GET /v1/users`. 25 at most. Defaults to none." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. Defaults to `in_app`." }, "task_title": { "nullable": true, "description": "The title of the task to add. Null adds no task.", "type": "string", "maxLength": 200 }, "task_body": { "nullable": true, "description": "The details of the task.", "type": "string", "maxLength": 2000 }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task, from `GET /v1/users`. Null gives it to the broker who sent the survey.", "type": "string", "minLength": 1 }, "task_due_in_days": { "type": "integer", "minimum": 0, "maximum": 90, "description": "The days from the answer until the task is due, from 0 to 90. Defaults to 2." }, "is_active": { "type": "boolean", "description": "False saves the rule stopped. Defaults to true." } }, "required": [ "name", "min_score", "max_score" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "nps_alert_rule", "description": "The type of this record. Always `nps_alert_rule`.", "type": "string", "enum": [ "nps_alert_rule" ] }, "id": { "type": "string", "description": "Stable identifier for the alert rule." }, "name": { "type": "string", "description": "The brokerage's name for the score range, for example `Unhappy client`. It starts each alert." }, "min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The lowest score the rule matches, from 0 to 10. The range includes it." }, "max_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The highest score the rule matches, from 0 to 10. The range includes it." }, "notify_owner": { "type": "boolean", "description": "True alerts the broker who sent the survey, in addition to the brokers in `broker_ids`." }, "broker_ids": { "type": "array", "items": { "type": "string" }, "description": "More brokers to alert. Resolve each with `GET /v1/users`." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. An alert always goes in the app." }, "task_title": { "nullable": true, "description": "The title of the task the rule adds on the client's contact. Null adds no task.", "type": "string" }, "task_body": { "nullable": true, "description": "The details of that task.", "type": "string" }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task. Null gives it to the broker who sent the survey.", "type": "string" }, "task_due_in_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The days from the answer until the task is due." }, "is_active": { "type": "boolean", "description": "False keeps the rule but stops it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the rule in the list. Every rule that matches runs." }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "When the rule last changed." } }, "required": [ "object", "id", "name", "min_score", "max_score", "notify_owner", "broker_ids", "channels", "task_title", "task_body", "task_assignee_user_id", "task_due_in_days", "is_active", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "`broker_ids` or `task_assignee_user_id` names a broker who is not in your brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/nps-alert-rules/{id}": { "get": { "operationId": "getNpsAlertRule", "summary": "Retrieve an NPS alert rule", "description": "One alert rule: its score range, who it alerts, and the task it adds.", "tags": [ "Client surveys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "nps_alert_rule", "description": "The type of this record. Always `nps_alert_rule`.", "type": "string", "enum": [ "nps_alert_rule" ] }, "id": { "type": "string", "description": "Stable identifier for the alert rule." }, "name": { "type": "string", "description": "The brokerage's name for the score range, for example `Unhappy client`. It starts each alert." }, "min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The lowest score the rule matches, from 0 to 10. The range includes it." }, "max_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The highest score the rule matches, from 0 to 10. The range includes it." }, "notify_owner": { "type": "boolean", "description": "True alerts the broker who sent the survey, in addition to the brokers in `broker_ids`." }, "broker_ids": { "type": "array", "items": { "type": "string" }, "description": "More brokers to alert. Resolve each with `GET /v1/users`." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. An alert always goes in the app." }, "task_title": { "nullable": true, "description": "The title of the task the rule adds on the client's contact. Null adds no task.", "type": "string" }, "task_body": { "nullable": true, "description": "The details of that task.", "type": "string" }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task. Null gives it to the broker who sent the survey.", "type": "string" }, "task_due_in_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The days from the answer until the task is due." }, "is_active": { "type": "boolean", "description": "False keeps the rule but stops it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the rule in the list. Every rule that matches runs." }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "When the rule last changed." } }, "required": [ "object", "id", "name", "min_score", "max_score", "notify_owner", "broker_ids", "channels", "task_title", "task_body", "task_assignee_user_id", "task_due_in_days", "is_active", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateNpsAlertRule", "summary": "Update an NPS alert rule", "description": "Changes the fields you send and keeps the others. The new range must still have `min_score` at or below `max_score`.", "tags": [ "Client surveys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The name for the score range. 120 characters at most." }, "min_score": { "type": "integer", "minimum": 0, "maximum": 10, "description": "The lowest score the rule matches, from 0 to 10." }, "max_score": { "type": "integer", "minimum": 0, "maximum": 10, "description": "The highest score the rule matches, from 0 to 10. It must not be below `min_score`." }, "notify_owner": { "type": "boolean", "description": "Alert the broker who sent the survey. Defaults to true." }, "broker_ids": { "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "More brokers to alert, from `GET /v1/users`. 25 at most. Defaults to none." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. Defaults to `in_app`." }, "task_title": { "nullable": true, "description": "The title of the task to add. Null adds no task.", "type": "string", "maxLength": 200 }, "task_body": { "nullable": true, "description": "The details of the task.", "type": "string", "maxLength": 2000 }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task, from `GET /v1/users`. Null gives it to the broker who sent the survey.", "type": "string", "minLength": 1 }, "task_due_in_days": { "type": "integer", "minimum": 0, "maximum": 90, "description": "The days from the answer until the task is due, from 0 to 90. Defaults to 2." }, "is_active": { "type": "boolean", "description": "False saves the rule stopped. Defaults to true." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "nps_alert_rule", "description": "The type of this record. Always `nps_alert_rule`.", "type": "string", "enum": [ "nps_alert_rule" ] }, "id": { "type": "string", "description": "Stable identifier for the alert rule." }, "name": { "type": "string", "description": "The brokerage's name for the score range, for example `Unhappy client`. It starts each alert." }, "min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The lowest score the rule matches, from 0 to 10. The range includes it." }, "max_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The highest score the rule matches, from 0 to 10. The range includes it." }, "notify_owner": { "type": "boolean", "description": "True alerts the broker who sent the survey, in addition to the brokers in `broker_ids`." }, "broker_ids": { "type": "array", "items": { "type": "string" }, "description": "More brokers to alert. Resolve each with `GET /v1/users`." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] }, "description": "How the alert reaches each broker: `in_app`, `email`, or both. An alert always goes in the app." }, "task_title": { "nullable": true, "description": "The title of the task the rule adds on the client's contact. Null adds no task.", "type": "string" }, "task_body": { "nullable": true, "description": "The details of that task.", "type": "string" }, "task_assignee_user_id": { "nullable": true, "description": "The broker who gets the task. Null gives it to the broker who sent the survey.", "type": "string" }, "task_due_in_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The days from the answer until the task is due." }, "is_active": { "type": "boolean", "description": "False keeps the rule but stops it." }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the rule in the list. Every rule that matches runs." }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "When the rule last changed." } }, "required": [ "object", "id", "name", "min_score", "max_score", "notify_owner", "broker_ids", "channels", "task_title", "task_body", "task_assignee_user_id", "task_due_in_days", "is_active", "position", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No alert rule in your brokerage has this id, or the rule names a broker who is not in your brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteNpsAlertRule", "summary": "Delete an NPS alert rule", "description": "Deletes the rule. Alerts it already sent and tasks it already added stay.", "tags": [ "Client surveys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No alert rule in your brokerage has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/nps-surveys": { "get": { "operationId": "listNpsSurveys", "summary": "List NPS surveys", "description": "The Net Promoter Score (NPS) surveys sent to the broker's clients, newest first, with each score and comment. A survey has no `updated_at`, so this list takes no `updated_since`: to pick up new answers, send `responded_since`. Every answer then comes back in `responded_at` order.", "tags": [ "Client surveys" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the surveys sent to this contact." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the surveys sent from this deal." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "viewed", "responded", "expired", "undelivered" ] }, "description": "Only the surveys with this status." }, { "name": "responded_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time. Only the surveys answered at or after it, oldest answer first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "nps_survey", "description": "The type of this record. Always `nps_survey`.", "type": "string", "enum": [ "nps_survey" ] }, "id": { "type": "string", "description": "Stable identifier for the survey." }, "contact_id": { "type": "string", "description": "The client the survey was sent to." }, "contact_name": { "type": "string", "description": "The client's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the survey was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the survey came from. Alerts for the answer go to this broker." }, "broker_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "responded", "expired", "undelivered" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `responded`: the client answered. `expired`: the link closed before an answer. `undelivered`: the email did not go out." }, "score": { "nullable": true, "description": "How likely the client is to recommend the broker, from 0 (not at all likely) to 10 (extremely likely). Null until the client answers.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "nullable": true, "description": "The standard NPS group of the score: `detractor` for 0 to 6, `passive` for 7 or 8, `promoter` for 9 or 10. Null until the client answers.", "type": "string", "enum": [ "detractor", "passive", "promoter" ] }, "comment": { "nullable": true, "description": "What the client wrote with the score, if anything.", "type": "string" }, "sent_by_automation": { "type": "boolean", "description": "True when an automation sent the survey. False when a broker, or a key, sent it." }, "sent_at": { "type": "string", "description": "When the survey was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "responded_at": { "nullable": true, "description": "When the client answered. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "broker_id", "broker_name", "status", "score", "band", "comment", "sent_by_automation", "sent_at", "viewed_at", "responded_at", "expires_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "sendNpsSurvey", "summary": "Send an NPS survey", "description": "Emails a client the NPS survey from BrokerPlus, now, from the broker's connected email. The response is the survey. A key with the `no_sending` limit cannot use this endpoint. Supports `Idempotency-Key`.", "tags": [ "Client surveys" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The client to survey. The client must have an email address, or send `email`." }, "email": { "description": "The address to send it to. When it differs from the contact's email, it replaces that email when the survey is sent, as in BrokerPlus.", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "deal_id": { "description": "The deal the survey is about, if any. The email carries the brand of that deal's team.", "type": "string", "minLength": 1 }, "message": { "description": "A note from the broker above the question. 2000 characters at most.", "type": "string", "maxLength": 2000 } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "nps_survey", "description": "The type of this record. Always `nps_survey`.", "type": "string", "enum": [ "nps_survey" ] }, "id": { "type": "string", "description": "Stable identifier for the survey." }, "contact_id": { "type": "string", "description": "The client the survey was sent to." }, "contact_name": { "type": "string", "description": "The client's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the survey was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the survey came from. Alerts for the answer go to this broker." }, "broker_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "responded", "expired", "undelivered" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `responded`: the client answered. `expired`: the link closed before an answer. `undelivered`: the email did not go out." }, "score": { "nullable": true, "description": "How likely the client is to recommend the broker, from 0 (not at all likely) to 10 (extremely likely). Null until the client answers.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "nullable": true, "description": "The standard NPS group of the score: `detractor` for 0 to 6, `passive` for 7 or 8, `promoter` for 9 or 10. Null until the client answers.", "type": "string", "enum": [ "detractor", "passive", "promoter" ] }, "comment": { "nullable": true, "description": "What the client wrote with the score, if anything.", "type": "string" }, "sent_by_automation": { "type": "boolean", "description": "True when an automation sent the survey. False when a broker, or a key, sent it." }, "sent_at": { "type": "string", "description": "When the survey was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "responded_at": { "nullable": true, "description": "When the client answered. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "broker_id", "broker_name", "status", "score", "band", "comment", "sent_by_automation", "sent_at", "viewed_at", "responded_at", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The client has no email address and you sent no `email` (NO_EMAIL).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key has the `no_sending` limit (KEY_LIMITED), or the broker cannot send to clients from BrokerPlus (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact or the deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker has no email connected (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "The email could not be sent. The survey is kept as `undelivered` (EMAIL_NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/nps-surveys/{id}": { "get": { "operationId": "getNpsSurvey", "summary": "Retrieve an NPS survey", "description": "One survey: who it went to, its status, and the client's score and comment.", "tags": [ "Client surveys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "nps_survey", "description": "The type of this record. Always `nps_survey`.", "type": "string", "enum": [ "nps_survey" ] }, "id": { "type": "string", "description": "Stable identifier for the survey." }, "contact_id": { "type": "string", "description": "The client the survey was sent to." }, "contact_name": { "type": "string", "description": "The client's name, for display." }, "deal_id": { "nullable": true, "description": "The deal the survey was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the survey came from. Alerts for the answer go to this broker." }, "broker_name": { "nullable": true, "description": "The name of that broker.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "responded", "expired", "undelivered" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `responded`: the client answered. `expired`: the link closed before an answer. `undelivered`: the email did not go out." }, "score": { "nullable": true, "description": "How likely the client is to recommend the broker, from 0 (not at all likely) to 10 (extremely likely). Null until the client answers.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "nullable": true, "description": "The standard NPS group of the score: `detractor` for 0 to 6, `passive` for 7 or 8, `promoter` for 9 or 10. Null until the client answers.", "type": "string", "enum": [ "detractor", "passive", "promoter" ] }, "comment": { "nullable": true, "description": "What the client wrote with the score, if anything.", "type": "string" }, "sent_by_automation": { "type": "boolean", "description": "True when an automation sent the survey. False when a broker, or a key, sent it." }, "sent_at": { "type": "string", "description": "When the survey was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "responded_at": { "nullable": true, "description": "When the client answered. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "broker_id", "broker_name", "status", "score", "band", "comment", "sent_by_automation", "sent_at", "viewed_at", "responded_at", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pep-forms": { "get": { "operationId": "listPepForms", "summary": "List PEP forms", "description": "The politically exposed person (PEP) declaration forms sent to the broker's clients, newest first. A form has no `updated_at`, so this list takes no `updated_since`: filter by `status` to find the forms that came back.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the forms sent to this contact." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the forms sent from this deal." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ] }, "description": "Only the forms with this status." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "pep_form", "description": "The type of this record. Always `pep_form`.", "type": "string", "enum": [ "pep_form" ] }, "id": { "type": "string", "description": "Stable identifier for the form." }, "contact_id": { "type": "string", "description": "The client the form was sent to." }, "client_name": { "type": "string", "description": "The client's name as it was when the form was sent." }, "email": { "type": "string", "description": "The address the form was sent to." }, "deal_id": { "nullable": true, "description": "The deal the form was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the form came from." }, "broker_name": { "type": "string", "description": "The name of that broker as it was when the form was sent." }, "application_number": { "nullable": true, "description": "The application number the broker printed on the form, if any.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `submitted`: the client answered and signed. `expired`: the link closed before an answer." }, "is_pep": { "nullable": true, "description": "Question 1: the client declared that they are, or are related to, a politically exposed person (PEP) or the head of an international organization. Null until the client answers.", "type": "boolean" }, "pep_type": { "nullable": true, "description": "Question 2: `foreign_pep`, `domestic_pep`, or `hio` (head of an international organization). Null until the client answers, or when `is_pep` is false.", "type": "string", "enum": [ "foreign_pep", "domestic_pep", "hio" ] }, "answers": { "nullable": true, "description": "The rest of the client's answers. Only the broker who sent the form and a compliance reviewer can read them, as with the signed declaration in BrokerPlus. Null for everyone else, and null until the client answers.", "type": "object", "properties": { "person_name": { "nullable": true, "description": "Question 3: the name of the politically exposed person.", "type": "string" }, "organization": { "nullable": true, "description": "Question 4: the organization where that person holds the position.", "type": "string" }, "country": { "nullable": true, "description": "Question 5: the country of the position.", "type": "string" }, "time_period": { "nullable": true, "description": "Question 6: when that person held the position.", "type": "string" }, "position": { "nullable": true, "description": "Question 7: the position.", "type": "string" }, "title": { "nullable": true, "description": "Question 8: the title.", "type": "string" }, "relationship": { "nullable": true, "description": "Question 9: how the client is related to that person.", "type": "string" }, "source_of_funds": { "nullable": true, "description": "Question 10: where the funds for the mortgage come from.", "type": "string" }, "signature_name": { "nullable": true, "description": "The name the client typed to sign the form.", "type": "string" }, "signed_at": { "nullable": true, "description": "When the client signed the form.", "type": "string" } }, "required": [ "person_name", "organization", "country", "time_period", "position", "title", "relationship", "source_of_funds", "signature_name", "signed_at" ], "additionalProperties": false }, "sent_at": { "type": "string", "description": "When the form was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the client submitted it. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "client_name", "email", "deal_id", "broker_id", "broker_name", "application_number", "status", "is_pep", "pep_type", "answers", "sent_at", "viewed_at", "submitted_at", "expires_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "sendPepForm", "summary": "Send a PEP form", "description": "Emails a client the PEP declaration form from BrokerPlus, now. The client gets a link to the form from the broker's connected email. The link works for 30 days. Only the broker assigned to the client, or an admin, can send the form. The response is the form. A key with the `no_sending` limit cannot use this endpoint. Supports `Idempotency-Key`.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "description": "The client to send the form to. The client needs a first name, a last name, and an email address on the contact." }, "application_number": { "description": "An application number to print on the form, if any. 100 characters at most.", "type": "string", "maxLength": 100 } }, "required": [ "contact_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pep_form", "description": "The type of this record. Always `pep_form`.", "type": "string", "enum": [ "pep_form" ] }, "id": { "type": "string", "description": "Stable identifier for the form." }, "contact_id": { "type": "string", "description": "The client the form was sent to." }, "client_name": { "type": "string", "description": "The client's name as it was when the form was sent." }, "email": { "type": "string", "description": "The address the form was sent to." }, "deal_id": { "nullable": true, "description": "The deal the form was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the form came from." }, "broker_name": { "type": "string", "description": "The name of that broker as it was when the form was sent." }, "application_number": { "nullable": true, "description": "The application number the broker printed on the form, if any.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `submitted`: the client answered and signed. `expired`: the link closed before an answer." }, "is_pep": { "nullable": true, "description": "Question 1: the client declared that they are, or are related to, a politically exposed person (PEP) or the head of an international organization. Null until the client answers.", "type": "boolean" }, "pep_type": { "nullable": true, "description": "Question 2: `foreign_pep`, `domestic_pep`, or `hio` (head of an international organization). Null until the client answers, or when `is_pep` is false.", "type": "string", "enum": [ "foreign_pep", "domestic_pep", "hio" ] }, "answers": { "nullable": true, "description": "The rest of the client's answers. Only the broker who sent the form and a compliance reviewer can read them, as with the signed declaration in BrokerPlus. Null for everyone else, and null until the client answers.", "type": "object", "properties": { "person_name": { "nullable": true, "description": "Question 3: the name of the politically exposed person.", "type": "string" }, "organization": { "nullable": true, "description": "Question 4: the organization where that person holds the position.", "type": "string" }, "country": { "nullable": true, "description": "Question 5: the country of the position.", "type": "string" }, "time_period": { "nullable": true, "description": "Question 6: when that person held the position.", "type": "string" }, "position": { "nullable": true, "description": "Question 7: the position.", "type": "string" }, "title": { "nullable": true, "description": "Question 8: the title.", "type": "string" }, "relationship": { "nullable": true, "description": "Question 9: how the client is related to that person.", "type": "string" }, "source_of_funds": { "nullable": true, "description": "Question 10: where the funds for the mortgage come from.", "type": "string" }, "signature_name": { "nullable": true, "description": "The name the client typed to sign the form.", "type": "string" }, "signed_at": { "nullable": true, "description": "When the client signed the form.", "type": "string" } }, "required": [ "person_name", "organization", "country", "time_period", "position", "title", "relationship", "source_of_funds", "signature_name", "signed_at" ], "additionalProperties": false }, "sent_at": { "type": "string", "description": "When the form was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the client submitted it. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "client_name", "email", "deal_id", "broker_id", "broker_name", "application_number", "status", "is_pep", "pep_type", "answers", "sent_at", "viewed_at", "submitted_at", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The client has no email address (MISSING_EMAIL), or no first or last name (MISSING_NAME).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The client is assigned to another broker, or the broker cannot send to clients from BrokerPlus (FORBIDDEN). The key has the `no_sending` limit (KEY_LIMITED). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The contact does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "412": { "description": "The broker has no email connected (EMAIL_NOT_CONNECTED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "502": { "description": "The email could not be sent. The form is kept, and the client got no link (EMAIL_NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/pep-forms/{id}": { "get": { "operationId": "getPepForm", "summary": "Retrieve a PEP form", "description": "One PEP declaration form: who it went to, its status, and the client's answers. Only the broker who sent the form and a compliance reviewer get the detailed answers in `answers`.", "tags": [ "Compliance forms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "pep_form", "description": "The type of this record. Always `pep_form`.", "type": "string", "enum": [ "pep_form" ] }, "id": { "type": "string", "description": "Stable identifier for the form." }, "contact_id": { "type": "string", "description": "The client the form was sent to." }, "client_name": { "type": "string", "description": "The client's name as it was when the form was sent." }, "email": { "type": "string", "description": "The address the form was sent to." }, "deal_id": { "nullable": true, "description": "The deal the form was sent from, if any. It is context only.", "type": "string" }, "broker_id": { "type": "string", "description": "The broker the form came from." }, "broker_name": { "type": "string", "description": "The name of that broker as it was when the form was sent." }, "application_number": { "nullable": true, "description": "The application number the broker printed on the form, if any.", "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "submitted", "expired" ], "description": "`sent`: emailed and not opened. `viewed`: the client opened it. `submitted`: the client answered and signed. `expired`: the link closed before an answer." }, "is_pep": { "nullable": true, "description": "Question 1: the client declared that they are, or are related to, a politically exposed person (PEP) or the head of an international organization. Null until the client answers.", "type": "boolean" }, "pep_type": { "nullable": true, "description": "Question 2: `foreign_pep`, `domestic_pep`, or `hio` (head of an international organization). Null until the client answers, or when `is_pep` is false.", "type": "string", "enum": [ "foreign_pep", "domestic_pep", "hio" ] }, "answers": { "nullable": true, "description": "The rest of the client's answers. Only the broker who sent the form and a compliance reviewer can read them, as with the signed declaration in BrokerPlus. Null for everyone else, and null until the client answers.", "type": "object", "properties": { "person_name": { "nullable": true, "description": "Question 3: the name of the politically exposed person.", "type": "string" }, "organization": { "nullable": true, "description": "Question 4: the organization where that person holds the position.", "type": "string" }, "country": { "nullable": true, "description": "Question 5: the country of the position.", "type": "string" }, "time_period": { "nullable": true, "description": "Question 6: when that person held the position.", "type": "string" }, "position": { "nullable": true, "description": "Question 7: the position.", "type": "string" }, "title": { "nullable": true, "description": "Question 8: the title.", "type": "string" }, "relationship": { "nullable": true, "description": "Question 9: how the client is related to that person.", "type": "string" }, "source_of_funds": { "nullable": true, "description": "Question 10: where the funds for the mortgage come from.", "type": "string" }, "signature_name": { "nullable": true, "description": "The name the client typed to sign the form.", "type": "string" }, "signed_at": { "nullable": true, "description": "When the client signed the form.", "type": "string" } }, "required": [ "person_name", "organization", "country", "time_period", "position", "title", "relationship", "source_of_funds", "signature_name", "signed_at" ], "additionalProperties": false }, "sent_at": { "type": "string", "description": "When the form was sent." }, "viewed_at": { "nullable": true, "description": "When the client first opened it. Null if never.", "type": "string" }, "submitted_at": { "nullable": true, "description": "When the client submitted it. Null until then.", "type": "string" }, "expires_at": { "type": "string", "description": "When the link stops taking an answer." } }, "required": [ "object", "id", "contact_id", "client_name", "email", "deal_id", "broker_id", "broker_name", "application_number", "status", "is_pep", "pep_type", "answers", "sent_at", "viewed_at", "submitted_at", "expires_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tracker-stages": { "get": { "operationId": "listTrackerStages", "summary": "List tracker stages", "description": "The stages of the client tracker, in order. The tracker belongs to the team that the key acts in, and every deal of that team shows these stages to its client. The list is not paginated: a tracker has at most 60 stages.", "tags": [ "Client tracker" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every stage of the tracker, in order." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The client tracker is not on for this account (FEATURE_UNAVAILABLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createTrackerStage", "summary": "Add a tracker stage", "description": "Adds a stage at the end of the tracker. If the team removed a stage with the same key, this brings it back, with the dates deals reached it. The client sees the new stage on every deal of the team at once, so a key with the `no_sending` limit cannot do this.", "tags": [ "Client tracker" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The stage name that the client reads. 1 to 60 characters." }, "description": { "description": "The sentence under the stage. Up to 240 characters.", "nullable": true, "type": "string", "maxLength": 240 }, "client_note": { "description": "The note from the broker while the deal is at this stage. Up to 1000 characters.", "nullable": true, "type": "string", "maxLength": 1000 }, "board_stage_keys": { "description": "The pipeline stage keys that match this stage. Up to 40. Defaults to none.", "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The broker is not on a team, or the label has no letter or number (NO_TEAM, READ_ONLY_TEAM, VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The tracker already has a stage with this key (DUPLICATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tracker-stages/note": { "get": { "operationId": "getTrackerNote", "summary": "Retrieve the tracker note", "description": "The note from the broker that the client's hub shows at a stage that has no note of its own.", "tags": [ "Client tracker" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "note": { "nullable": true, "description": "The note from the broker that the hub shows at a stage that has no `client_note`. Null if none.", "type": "string" } }, "required": [ "note" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateTrackerNote", "summary": "Update the tracker note", "description": "Sets the note that the client's hub shows at a stage that has no note of its own. The client sees it at once, so a key with the `no_sending` limit cannot do this.", "tags": [ "Client tracker" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "nullable": true, "description": "The new note. Up to 1000 characters. Null or an empty string removes it.", "type": "string", "maxLength": 1000 } }, "required": [ "note" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "note": { "nullable": true, "description": "The note from the broker that the hub shows at a stage that has no `client_note`. Null if none.", "type": "string" } }, "required": [ "note" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tracker-stages/reorder": { "post": { "operationId": "reorderTrackerStages", "summary": "Reorder tracker stages", "description": "Sets the order of every stage of the tracker. Send every stage id once. Returns the stages in the new order. The client sees the new order at once, so a key with the `no_sending` limit cannot do this.", "tags": [ "Client tracker" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "string" }, "description": "Every stage id of the tracker, in the new order. Send each stage once, and no other id." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every stage of the tracker, in order." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The ids are not every stage of the tracker, each once (STALE_ORDER).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tracker-stages/seed": { "post": { "operationId": "seedTrackerStages", "summary": "Fill an empty tracker", "description": "Adds the standard five stages to a tracker that has none. It never changes a tracker that has a stage. The client sees the stages at once, so a key with the `no_sending` limit cannot do this.", "tags": [ "Client tracker" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Every stage of the tracker, in order." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The tracker already has stages (ALREADY_SEEDED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/tracker-stages/{id}": { "get": { "operationId": "getTrackerStage", "summary": "Retrieve a tracker stage", "description": "One stage of the tracker of the team that the key acts in. A removed stage is not found.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateTrackerStage", "summary": "Update a tracker stage", "description": "Changes what the client reads, or which pipeline stages match. The `key` does not change, so the automations that name the stage keep working. The client sees the change at once, so a key with the `no_sending` limit cannot do this.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "description": "The new stage name. The `key` stays the same.", "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "description": "The new sentence under the stage. Null removes it.", "nullable": true, "type": "string", "maxLength": 240 }, "client_note": { "description": "The new note for this stage. Null removes it.", "nullable": true, "type": "string", "maxLength": 1000 }, "board_stage_keys": { "description": "The pipeline stage keys that match this stage. Replaces the list.", "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tracker_stage", "description": "The type of this record. Always `tracker_stage`.", "type": "string", "enum": [ "tracker_stage" ] }, "id": { "type": "string", "description": "Stable identifier for the tracker stage." }, "team_id": { "type": "string", "description": "The team whose tracker the stage is on. Every deal of the team shows the same stages." }, "key": { "type": "string", "description": "A stable name for the stage, made from its first label. It does not change when the label changes. Automations name a stage by its key." }, "label": { "type": "string", "description": "The stage name that the client reads, for example `Appraisal Booked`." }, "description": { "nullable": true, "description": "The sentence that the client reads under the stage. Null if none.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows while the deal is at this stage. Null uses the team's note from `GET /v1/tracker-stages/note`.", "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the stage on the tracker, from 0." }, "board_stage_keys": { "type": "array", "items": { "type": "string" }, "description": "The pipeline stage keys that match this stage. When the deal's pipeline stage and the tracker disagree, `drift` on the deal tracker says so. Empty means only the broker moves the deal to this stage." }, "created_at": { "type": "string", "description": "When the stage was added." }, "updated_at": { "type": "string", "description": "When the stage last changed." } }, "required": [ "object", "id", "team_id", "key", "label", "description", "client_note", "position", "board_stage_keys", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteTrackerStage", "summary": "Remove a tracker stage", "description": "Removes the stage from the tracker of every deal. BrokerPlus keeps the dates deals reached it: add a stage with the same key to bring it back with them.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tracker": { "get": { "operationId": "getDealTracker", "summary": "Retrieve a deal's tracker", "description": "The client tracker of one deal, as the client sees it: each stage, the day the deal reached it, the note from the broker, and whether the tracker disagrees with the deal's pipeline stage.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "The tracker stage. See `GET /v1/tracker-stages/{id}`." }, "key": { "type": "string", "description": "The stage key." }, "label": { "type": "string", "description": "The stage name that the client reads." }, "description": { "nullable": true, "description": "The sentence under the stage. Null if none.", "type": "string" }, "reached": { "type": "boolean", "description": "`true` if the client sees the stage as reached." }, "reached_on": { "nullable": true, "description": "The day the deal reached the stage, as `YYYY-MM-DD`. Null if not reached.", "type": "string" }, "reached_by_user_id": { "nullable": true, "description": "The broker who showed the stage as reached. Null if not reached, or if nobody did.", "type": "string" }, "current": { "type": "boolean", "description": "`true` for the furthest stage reached. At most one stage is current." } }, "required": [ "stage_id", "key", "label", "description", "reached", "reached_on", "reached_by_user_id", "current" ], "additionalProperties": false }, "description": "Every stage of the team's tracker, in order. A stage can be reached while an earlier stage is not: the client then sees the gap." }, "current_stage_id": { "nullable": true, "description": "The furthest stage reached. Null before the first one.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows now. Null if none.", "type": "string" }, "drift": { "nullable": true, "description": "Set when the tracker and the deal's pipeline stage disagree. BrokerPlus changes neither: the broker decides. Null when they agree, or when the pipeline stage matches no tracker stage.", "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ahead", "behind" ], "description": "`ahead`: the tracker shows a later stage than the pipeline stage matches. `behind`: the pipeline moved on and the tracker did not." }, "tracker_stage_label": { "nullable": true, "description": "The furthest stage that the client sees as reached.", "type": "string" }, "matching_stage_label": { "nullable": true, "description": "The tracker stage that the pipeline stage matches.", "type": "string" }, "pipeline_stage_label": { "nullable": true, "description": "The deal's pipeline stage.", "type": "string" } }, "required": [ "direction", "tracker_stage_label", "matching_stage_label", "pipeline_stage_label" ], "additionalProperties": false } }, "required": [ "deal_id", "stages", "current_stage_id", "client_note", "drift" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tracker/{stageId}/reach": { "post": { "operationId": "reachDealTrackerStage", "summary": "Show a stage as reached", "description": "Shows the stage as reached now, the same as a click on the stage in BrokerPlus. The client sees the stage as reached, with every earlier stage, and the automations and partner updates that start on a reached stage run. The response is the deal's tracker. A key with the `no_sending` limit cannot do this. Supports `Idempotency-Key`.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "stageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reached_on": { "description": "The day the deal reached the stage, as `YYYY-MM-DD`. The client sees this date. Defaults to today. On a stage the deal already reached, this changes its date.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "The tracker stage. See `GET /v1/tracker-stages/{id}`." }, "key": { "type": "string", "description": "The stage key." }, "label": { "type": "string", "description": "The stage name that the client reads." }, "description": { "nullable": true, "description": "The sentence under the stage. Null if none.", "type": "string" }, "reached": { "type": "boolean", "description": "`true` if the client sees the stage as reached." }, "reached_on": { "nullable": true, "description": "The day the deal reached the stage, as `YYYY-MM-DD`. Null if not reached.", "type": "string" }, "reached_by_user_id": { "nullable": true, "description": "The broker who showed the stage as reached. Null if not reached, or if nobody did.", "type": "string" }, "current": { "type": "boolean", "description": "`true` for the furthest stage reached. At most one stage is current." } }, "required": [ "stage_id", "key", "label", "description", "reached", "reached_on", "reached_by_user_id", "current" ], "additionalProperties": false }, "description": "Every stage of the team's tracker, in order. A stage can be reached while an earlier stage is not: the client then sees the gap." }, "current_stage_id": { "nullable": true, "description": "The furthest stage reached. Null before the first one.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows now. Null if none.", "type": "string" }, "drift": { "nullable": true, "description": "Set when the tracker and the deal's pipeline stage disagree. BrokerPlus changes neither: the broker decides. Null when they agree, or when the pipeline stage matches no tracker stage.", "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ahead", "behind" ], "description": "`ahead`: the tracker shows a later stage than the pipeline stage matches. `behind`: the pipeline moved on and the tracker did not." }, "tracker_stage_label": { "nullable": true, "description": "The furthest stage that the client sees as reached.", "type": "string" }, "matching_stage_label": { "nullable": true, "description": "The tracker stage that the pipeline stage matches.", "type": "string" }, "pipeline_stage_label": { "nullable": true, "description": "The deal's pipeline stage.", "type": "string" } }, "required": [ "direction", "tracker_stage_label", "matching_stage_label", "pipeline_stage_label" ], "additionalProperties": false } }, "required": [ "deal_id", "stages", "current_stage_id", "client_note", "drift" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "Your key has the `no_sending` limit (KEY_LIMITED), or the broker your key acts as may not contact clients (FORBIDDEN). Your brokerage's automation policy does not allow messages to clients to be asked for this way (POLICY_BLOCKED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, the broker cannot change it, or the stage is not on its tracker (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The stage is no longer on the deal's tracker (NOT_SENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tracker/{stageId}/retract": { "post": { "operationId": "retractDealTrackerStage", "summary": "Take a stage back down", "description": "The client no longer sees the stage as reached, and every later stage goes back down with it. BrokerPlus forgets the dates of those stages. This sends nothing and starts no automation, so a key with the `no_sending` limit can do it. A stage that is not reached stays as it is.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "stageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "The deal." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "The tracker stage. See `GET /v1/tracker-stages/{id}`." }, "key": { "type": "string", "description": "The stage key." }, "label": { "type": "string", "description": "The stage name that the client reads." }, "description": { "nullable": true, "description": "The sentence under the stage. Null if none.", "type": "string" }, "reached": { "type": "boolean", "description": "`true` if the client sees the stage as reached." }, "reached_on": { "nullable": true, "description": "The day the deal reached the stage, as `YYYY-MM-DD`. Null if not reached.", "type": "string" }, "reached_by_user_id": { "nullable": true, "description": "The broker who showed the stage as reached. Null if not reached, or if nobody did.", "type": "string" }, "current": { "type": "boolean", "description": "`true` for the furthest stage reached. At most one stage is current." } }, "required": [ "stage_id", "key", "label", "description", "reached", "reached_on", "reached_by_user_id", "current" ], "additionalProperties": false }, "description": "Every stage of the team's tracker, in order. A stage can be reached while an earlier stage is not: the client then sees the gap." }, "current_stage_id": { "nullable": true, "description": "The furthest stage reached. Null before the first one.", "type": "string" }, "client_note": { "nullable": true, "description": "The note from the broker that the client's hub shows now. Null if none.", "type": "string" }, "drift": { "nullable": true, "description": "Set when the tracker and the deal's pipeline stage disagree. BrokerPlus changes neither: the broker decides. Null when they agree, or when the pipeline stage matches no tracker stage.", "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ahead", "behind" ], "description": "`ahead`: the tracker shows a later stage than the pipeline stage matches. `behind`: the pipeline moved on and the tracker did not." }, "tracker_stage_label": { "nullable": true, "description": "The furthest stage that the client sees as reached.", "type": "string" }, "matching_stage_label": { "nullable": true, "description": "The tracker stage that the pipeline stage matches.", "type": "string" }, "pipeline_stage_label": { "nullable": true, "description": "The deal's pipeline stage.", "type": "string" } }, "required": [ "direction", "tracker_stage_label", "matching_stage_label", "pipeline_stage_label" ], "additionalProperties": false } }, "required": [ "deal_id", "stages", "current_stage_id", "client_note", "drift" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, the broker cannot change it, or the stage is not on its tracker (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tracker/links": { "get": { "operationId": "listDealTrackerLinks", "summary": "List the deal's tracker links", "description": "The links that still show this deal's tracker to a realtor, a lawyer or someone else outside the brokerage, newest first. BrokerPlus no longer makes these links: a partner now gets one partner hub for every file, with `POST /partner-hubs`. A link does not include its address, which BrokerPlus never kept.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "tracker_link", "description": "The type of this record. Always `tracker_link`.", "type": "string", "enum": [ "tracker_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "deal_id": { "type": "string", "description": "The deal whose tracker the link shows." }, "recipient_name": { "nullable": true, "description": "Who the link was made for. Null if the broker gave no name.", "type": "string" }, "recipient_email": { "nullable": true, "description": "The address of the person the link was made for. Null if none.", "type": "string" }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "other" ], "description": "`realtor`, `lawyer` or `other`. A label for the broker: every link shows the same tracker." }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the link was opened." }, "last_viewed_at": { "nullable": true, "description": "When the link was last opened. Null if never.", "type": "string" }, "revoked_at": { "nullable": true, "description": "When the broker took the link back. It stops working then. Null while it works.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was made." } }, "required": [ "object", "id", "deal_id", "recipient_name", "recipient_email", "role", "view_count", "last_viewed_at", "revoked_at", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/tracker/links/{linkId}/revoke": { "post": { "operationId": "revokeDealTrackerLink", "summary": "Take back a tracker link", "description": "The link stops working at once, as **Revoke** on the link in BrokerPlus. BrokerPlus keeps it with `revoked_at` set, so the broker can see it was used. Nobody is told.", "tags": [ "Client tracker" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "tracker_link", "description": "The type of this record. Always `tracker_link`.", "type": "string", "enum": [ "tracker_link" ] }, "id": { "type": "string", "description": "Stable identifier for the link." }, "deal_id": { "type": "string", "description": "The deal whose tracker the link shows." }, "recipient_name": { "nullable": true, "description": "Who the link was made for. Null if the broker gave no name.", "type": "string" }, "recipient_email": { "nullable": true, "description": "The address of the person the link was made for. Null if none.", "type": "string" }, "role": { "type": "string", "enum": [ "realtor", "lawyer", "other" ], "description": "`realtor`, `lawyer` or `other`. A label for the broker: every link shows the same tracker." }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the link was opened." }, "last_viewed_at": { "nullable": true, "description": "When the link was last opened. Null if never.", "type": "string" }, "revoked_at": { "nullable": true, "description": "When the broker took the link back. It stops working then. Null while it works.", "type": "string" }, "created_at": { "type": "string", "description": "When the link was made." } }, "required": [ "object", "id", "deal_id", "recipient_name", "recipient_email", "role", "view_count", "last_viewed_at", "revoked_at", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, the broker cannot change it, or the link is not live on it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/suggestions": { "get": { "operationId": "listSuggestions", "summary": "List suggestions", "description": "The changes that BrokerPlus suggests to the broker, as the deal, the inbox, and the work queue show them. Newest first, or oldest first with `updated_since`.", "tags": [ "Suggestions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "stale", "dismissed", "executed", "cancelled" ] }, "description": "Return only suggestions in this state. Send `pending` for the ones that wait for a decision." }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only suggestions about this deal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "suggestion", "description": "The type of this record. Always `suggestion`.", "type": "string", "enum": [ "suggestion" ] }, "id": { "type": "string", "description": "Stable identifier for the suggestion." }, "kind": { "type": "string", "description": "What the suggestion does, e.g. `contact_create`, `contact_update`, `deal_field_update`, `stage_move`, `task_create`, `document_file`, `draft_email`, or `agent_tool_action`. BrokerPlus can add kinds." }, "title": { "type": "string", "description": "The sentence the broker sees on the suggestion card, e.g. `Add Sam Lee as a contact`." }, "status": { "type": "string", "enum": [ "pending", "stale", "dismissed", "executed", "cancelled" ], "description": "`pending` waits for a decision. `stale` means the facts it was based on changed. `dismissed` was turned down, `executed` was approved and done, and `cancelled` was withdrawn by BrokerPlus." }, "values": { "type": "object", "additionalProperties": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "The values the suggestion writes, by name, as the card shows them, e.g. `first_name` and `email` on `contact_create`. Empty when the suggestion comes from mail in a mailbox that your key cannot read." }, "approvable": { "type": "boolean", "description": "True when your key can approve the suggestion now. False when it is not pending, or when it reaches a client, acts outside BrokerPlus, or opens a draft: the broker approves those in BrokerPlus." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "subject_type": { "nullable": true, "description": "The kind of record it came from, e.g. `communication`. Null when it came from no single record.", "type": "string" }, "subject_id": { "nullable": true, "description": "The id of the record it came from.", "type": "string" }, "bundle_key": { "nullable": true, "description": "Suggestions that share a `bundle_key` came from one event, and the broker reviews them together.", "type": "string" }, "bundle_label": { "nullable": true, "description": "The name of the bundle, for display.", "type": "string" }, "task_id": { "nullable": true, "description": "The task that asks the broker to approve the suggestion, when there is one. Resolve against `GET /tasks/{id}`. It is the same approval, not a second one.", "type": "string" }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant made the suggestion." }, "expires_at": { "nullable": true, "description": "When the suggestion lapses. Null if it does not.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When it was dismissed.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "The reason given for the dismissal.", "type": "string" }, "executed_at": { "nullable": true, "description": "When it was approved and done.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus made the suggestion." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "kind", "title", "status", "values", "approvable", "deal_id", "deal_name", "subject_type", "subject_id", "bundle_key", "bundle_label", "task_id", "created_by_agent", "expires_at", "dismissed_at", "dismiss_reason", "executed_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/suggestions/{id}": { "get": { "operationId": "getSuggestion", "summary": "Retrieve a suggestion", "description": "One suggestion, its values, and whether your key can approve it.", "tags": [ "Suggestions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "suggestion", "description": "The type of this record. Always `suggestion`.", "type": "string", "enum": [ "suggestion" ] }, "id": { "type": "string", "description": "Stable identifier for the suggestion." }, "kind": { "type": "string", "description": "What the suggestion does, e.g. `contact_create`, `contact_update`, `deal_field_update`, `stage_move`, `task_create`, `document_file`, `draft_email`, or `agent_tool_action`. BrokerPlus can add kinds." }, "title": { "type": "string", "description": "The sentence the broker sees on the suggestion card, e.g. `Add Sam Lee as a contact`." }, "status": { "type": "string", "enum": [ "pending", "stale", "dismissed", "executed", "cancelled" ], "description": "`pending` waits for a decision. `stale` means the facts it was based on changed. `dismissed` was turned down, `executed` was approved and done, and `cancelled` was withdrawn by BrokerPlus." }, "values": { "type": "object", "additionalProperties": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "The values the suggestion writes, by name, as the card shows them, e.g. `first_name` and `email` on `contact_create`. Empty when the suggestion comes from mail in a mailbox that your key cannot read." }, "approvable": { "type": "boolean", "description": "True when your key can approve the suggestion now. False when it is not pending, or when it reaches a client, acts outside BrokerPlus, or opens a draft: the broker approves those in BrokerPlus." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "subject_type": { "nullable": true, "description": "The kind of record it came from, e.g. `communication`. Null when it came from no single record.", "type": "string" }, "subject_id": { "nullable": true, "description": "The id of the record it came from.", "type": "string" }, "bundle_key": { "nullable": true, "description": "Suggestions that share a `bundle_key` came from one event, and the broker reviews them together.", "type": "string" }, "bundle_label": { "nullable": true, "description": "The name of the bundle, for display.", "type": "string" }, "task_id": { "nullable": true, "description": "The task that asks the broker to approve the suggestion, when there is one. Resolve against `GET /tasks/{id}`. It is the same approval, not a second one.", "type": "string" }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant made the suggestion." }, "expires_at": { "nullable": true, "description": "When the suggestion lapses. Null if it does not.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When it was dismissed.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "The reason given for the dismissal.", "type": "string" }, "executed_at": { "nullable": true, "description": "When it was approved and done.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus made the suggestion." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "kind", "title", "status", "values", "approvable", "deal_id", "deal_name", "subject_type", "subject_id", "bundle_key", "bundle_label", "task_id", "created_by_agent", "expires_at", "dismissed_at", "dismiss_reason", "executed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/suggestions/{id}/approve": { "post": { "operationId": "approveSuggestion", "summary": "Approve a suggestion", "description": "Carries out a pending suggestion as the broker your key acts as, and returns it as `executed`. Only a suggestion with `approvable` true can be approved this way. A suggestion that reaches a client, acts outside BrokerPlus, or opens a draft waits for the broker in BrokerPlus.", "tags": [ "Suggestions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "suggestion", "description": "The type of this record. Always `suggestion`.", "type": "string", "enum": [ "suggestion" ] }, "id": { "type": "string", "description": "Stable identifier for the suggestion." }, "kind": { "type": "string", "description": "What the suggestion does, e.g. `contact_create`, `contact_update`, `deal_field_update`, `stage_move`, `task_create`, `document_file`, `draft_email`, or `agent_tool_action`. BrokerPlus can add kinds." }, "title": { "type": "string", "description": "The sentence the broker sees on the suggestion card, e.g. `Add Sam Lee as a contact`." }, "status": { "type": "string", "enum": [ "pending", "stale", "dismissed", "executed", "cancelled" ], "description": "`pending` waits for a decision. `stale` means the facts it was based on changed. `dismissed` was turned down, `executed` was approved and done, and `cancelled` was withdrawn by BrokerPlus." }, "values": { "type": "object", "additionalProperties": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "The values the suggestion writes, by name, as the card shows them, e.g. `first_name` and `email` on `contact_create`. Empty when the suggestion comes from mail in a mailbox that your key cannot read." }, "approvable": { "type": "boolean", "description": "True when your key can approve the suggestion now. False when it is not pending, or when it reaches a client, acts outside BrokerPlus, or opens a draft: the broker approves those in BrokerPlus." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "subject_type": { "nullable": true, "description": "The kind of record it came from, e.g. `communication`. Null when it came from no single record.", "type": "string" }, "subject_id": { "nullable": true, "description": "The id of the record it came from.", "type": "string" }, "bundle_key": { "nullable": true, "description": "Suggestions that share a `bundle_key` came from one event, and the broker reviews them together.", "type": "string" }, "bundle_label": { "nullable": true, "description": "The name of the bundle, for display.", "type": "string" }, "task_id": { "nullable": true, "description": "The task that asks the broker to approve the suggestion, when there is one. Resolve against `GET /tasks/{id}`. It is the same approval, not a second one.", "type": "string" }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant made the suggestion." }, "expires_at": { "nullable": true, "description": "When the suggestion lapses. Null if it does not.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When it was dismissed.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "The reason given for the dismissal.", "type": "string" }, "executed_at": { "nullable": true, "description": "When it was approved and done.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus made the suggestion." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "kind", "title", "status", "values", "approvable", "deal_id", "deal_name", "subject_type", "subject_id", "bundle_key", "bundle_label", "task_id", "created_by_agent", "expires_at", "dismissed_at", "dismiss_reason", "executed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The broker must approve the suggestion in BrokerPlus (APPROVE_IN_BROKERPLUS), it is not pending (NOT_PENDING), its facts changed (STALE), or another approval runs now (CONFLICT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "BrokerPlus could not carry it out (EXECUTION_FAILED), or the deal is a test deal (REFUSED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/suggestions/{id}/dismiss": { "post": { "operationId": "dismissSuggestion", "summary": "Dismiss a suggestion", "description": "Turns down a pending or stale suggestion. Nothing is written, and the approval task for it closes. The broker sees the reason that you send.", "tags": [ "Suggestions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why you turned it down. The broker sees it.", "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "suggestion", "description": "The type of this record. Always `suggestion`.", "type": "string", "enum": [ "suggestion" ] }, "id": { "type": "string", "description": "Stable identifier for the suggestion." }, "kind": { "type": "string", "description": "What the suggestion does, e.g. `contact_create`, `contact_update`, `deal_field_update`, `stage_move`, `task_create`, `document_file`, `draft_email`, or `agent_tool_action`. BrokerPlus can add kinds." }, "title": { "type": "string", "description": "The sentence the broker sees on the suggestion card, e.g. `Add Sam Lee as a contact`." }, "status": { "type": "string", "enum": [ "pending", "stale", "dismissed", "executed", "cancelled" ], "description": "`pending` waits for a decision. `stale` means the facts it was based on changed. `dismissed` was turned down, `executed` was approved and done, and `cancelled` was withdrawn by BrokerPlus." }, "values": { "type": "object", "additionalProperties": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "The values the suggestion writes, by name, as the card shows them, e.g. `first_name` and `email` on `contact_create`. Empty when the suggestion comes from mail in a mailbox that your key cannot read." }, "approvable": { "type": "boolean", "description": "True when your key can approve the suggestion now. False when it is not pending, or when it reaches a client, acts outside BrokerPlus, or opens a draft: the broker approves those in BrokerPlus." }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "subject_type": { "nullable": true, "description": "The kind of record it came from, e.g. `communication`. Null when it came from no single record.", "type": "string" }, "subject_id": { "nullable": true, "description": "The id of the record it came from.", "type": "string" }, "bundle_key": { "nullable": true, "description": "Suggestions that share a `bundle_key` came from one event, and the broker reviews them together.", "type": "string" }, "bundle_label": { "nullable": true, "description": "The name of the bundle, for display.", "type": "string" }, "task_id": { "nullable": true, "description": "The task that asks the broker to approve the suggestion, when there is one. Resolve against `GET /tasks/{id}`. It is the same approval, not a second one.", "type": "string" }, "created_by_agent": { "type": "boolean", "description": "True when the BrokerPlus assistant made the suggestion." }, "expires_at": { "nullable": true, "description": "When the suggestion lapses. Null if it does not.", "type": "string" }, "dismissed_at": { "nullable": true, "description": "When it was dismissed.", "type": "string" }, "dismiss_reason": { "nullable": true, "description": "The reason given for the dismissal.", "type": "string" }, "executed_at": { "nullable": true, "description": "When it was approved and done.", "type": "string" }, "created_at": { "type": "string", "description": "When BrokerPlus made the suggestion." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "kind", "title", "status", "values", "approvable", "deal_id", "deal_name", "subject_type", "subject_id", "bundle_key", "bundle_label", "task_id", "created_by_agent", "expires_at", "dismissed_at", "dismiss_reason", "executed_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The suggestion is already decided, or it runs now (NOT_DISMISSIBLE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/notifications": { "get": { "operationId": "listNotifications", "summary": "List notifications", "description": "The notifications in the bell of the broker your key acts as, newest first. A teammate's notifications are never included.", "tags": [ "Notifications" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send `true` to return only unread notifications." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only notifications that arrived or were read at or after it. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "notification", "description": "The type of this record. Always `notification`.", "type": "string", "enum": [ "notification" ] }, "id": { "type": "string", "description": "Stable identifier for the notification." }, "type": { "type": "string", "description": "What the notification is about, e.g. `mention`, `task_assigned`, or `lender_response`. BrokerPlus can add types." }, "title": { "type": "string", "description": "The headline the broker sees in the bell." }, "body": { "nullable": true, "description": "The text under the headline. Null when there is none.", "type": "string" }, "is_read": { "type": "boolean", "description": "True when the broker read it." }, "read_at": { "nullable": true, "description": "When it was read. Null while it is unread.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "created_at": { "type": "string", "description": "When the notification arrived." } }, "required": [ "object", "id", "type", "title", "body", "is_read", "read_at", "deal_id", "deal_name", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/notifications/{id}/read": { "post": { "operationId": "markNotificationRead", "summary": "Mark a notification read", "description": "Marks one notification read. A notification that is already read keeps the time it was first read. Reading a mention also marks the mention seen.", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "notification", "description": "The type of this record. Always `notification`.", "type": "string", "enum": [ "notification" ] }, "id": { "type": "string", "description": "Stable identifier for the notification." }, "type": { "type": "string", "description": "What the notification is about, e.g. `mention`, `task_assigned`, or `lender_response`. BrokerPlus can add types." }, "title": { "type": "string", "description": "The headline the broker sees in the bell." }, "body": { "nullable": true, "description": "The text under the headline. Null when there is none.", "type": "string" }, "is_read": { "type": "boolean", "description": "True when the broker read it." }, "read_at": { "nullable": true, "description": "When it was read. Null while it is unread.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it is about. Null when it is about no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "created_at": { "type": "string", "description": "When the notification arrived." } }, "required": [ "object", "id", "type", "title", "body", "is_read", "read_at", "deal_id", "deal_name", "created_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/notifications/read-all": { "post": { "operationId": "markAllNotificationsRead", "summary": "Mark every notification read", "description": "Marks every unread notification of the broker read, and returns how many it marked.", "tags": [ "Notifications" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many notifications this call marked read. 0 when all were read." } }, "required": [ "updated" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance": { "get": { "operationId": "getDealCompliance", "summary": "Read a deal's compliance checklist", "description": "The compliance checklist of the deal, as the broker sees it on the deal: the checkpoints, the open items, the state of the identity, know-your-client, and screening checks on each party, the consents, the suitability answers, and the required documents. This is a read. The ID documents, ID numbers, dates of birth, and screening results are not published.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_compliance", "description": "The type of this record. Always `deal_compliance`.", "type": "string", "enum": [ "deal_compliance" ] }, "deal_id": { "type": "string", "description": "The deal." }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The checkpoint: `intake_credit`, `lender_submission`, `commitment_signing`, `funding`, or `file_close`." }, "label": { "type": "string", "description": "The name of the checkpoint, for display." }, "status": { "type": "string", "description": "The state of the checkpoint, e.g. `ready`, `blocked`, or `pending`." }, "blocker_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The items in `blockers` that hold this checkpoint." }, "pending_reason": { "nullable": true, "description": "Why BrokerPlus cannot decide the checkpoint yet.", "type": "string" } }, "required": [ "key", "label", "status", "blocker_count", "pending_reason" ], "additionalProperties": false }, "description": "The compliance checkpoints of the deal, in order. This is the checklist the broker sees on the deal." }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the item, on this deal." }, "checkpoint": { "type": "string", "description": "The checkpoint the item holds." }, "title": { "type": "string", "description": "What is missing, as the broker sees it." }, "reason": { "nullable": true, "description": "Why it is required.", "type": "string" }, "severity": { "type": "string", "description": "`blocker`, `warning`, or `info`." }, "contact_id": { "nullable": true, "description": "The party it is about. Null when it is about the deal.", "type": "string" }, "due_at": { "nullable": true, "description": "When it is due. Null when it has no date.", "type": "string" } }, "required": [ "id", "checkpoint", "title", "reason", "severity", "contact_id", "due_at" ], "additionalProperties": false }, "description": "The open items on the checklist. An item that the broker recorded as done outside BrokerPlus is not here." }, "parties": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The party. Resolve against `GET /contacts/{id}`." }, "name": { "type": "string", "description": "The party's name, for display." }, "role": { "type": "string", "description": "The party's role on the deal, e.g. `primary_applicant`." }, "is_entity": { "type": "boolean", "description": "True for a company or a trust." }, "identity": { "type": "object", "properties": { "status": { "type": "string", "description": "The state of the identity verification: `cleared`, `verified`, `pending`, `processing`, `attention`, `failed`, `expired`, `missing`, or `not_applicable`." }, "completed_at": { "nullable": true, "description": "When the identity verification was completed. Null until it is.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the identity verification lapses. Null if it does not.", "type": "string" }, "method": { "nullable": true, "description": "How the identity was verified, e.g. `dual_process`.", "type": "string" } }, "required": [ "status", "completed_at", "expires_at", "method" ], "additionalProperties": false, "description": "The identity verification. The ID document, its images, and its number are not published." }, "kyc": { "type": "object", "properties": { "status": { "type": "string", "description": "The state of the know-your-client record: `cleared`, `verified`, `pending`, `processing`, `attention`, `failed`, `expired`, `missing`, or `not_applicable`." }, "completed_at": { "nullable": true, "description": "When the know-your-client record was completed. Null until it is.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the know-your-client record lapses. Null if it does not.", "type": "string" }, "has_record": { "type": "boolean", "description": "True when a know-your-client record is on file." } }, "required": [ "status", "completed_at", "expires_at", "has_record" ], "additionalProperties": false, "description": "The know-your-client record." }, "aml_screening": { "type": "object", "properties": { "status": { "type": "string", "description": "The state of the anti-money-laundering screening: `cleared`, `verified`, `pending`, `processing`, `attention`, `failed`, `expired`, `missing`, or `not_applicable`." }, "completed_at": { "nullable": true, "description": "When the anti-money-laundering screening was completed. Null until it is.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the anti-money-laundering screening lapses. Null if it does not.", "type": "string" }, "next_screening_at": { "nullable": true, "description": "When the next screening is due.", "type": "string" } }, "required": [ "status", "completed_at", "expires_at", "next_screening_at" ], "additionalProperties": false, "description": "The politically exposed person and sanctions screening." }, "risk_rating": { "type": "object", "properties": { "status": { "type": "string", "description": "The state of the risk rating: `cleared`, `verified`, `pending`, `processing`, `attention`, `failed`, `expired`, `missing`, or `not_applicable`." }, "completed_at": { "nullable": true, "description": "When the risk rating was completed. Null until it is.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the risk rating lapses. Null if it does not.", "type": "string" } }, "required": [ "status", "completed_at", "expires_at" ], "additionalProperties": false, "description": "Whether the client has a risk rating." }, "pep": { "type": "object", "properties": { "status": { "type": "string", "description": "The state of the politically exposed person determination: `cleared`, `verified`, `pending`, `processing`, `attention`, `failed`, `expired`, `missing`, or `not_applicable`." }, "completed_at": { "nullable": true, "description": "When the politically exposed person determination was completed. Null until it is.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the politically exposed person determination lapses. Null if it does not.", "type": "string" } }, "required": [ "status", "completed_at", "expires_at" ], "additionalProperties": false, "description": "Whether the politically exposed person question has an answer." } }, "required": [ "contact_id", "name", "role", "is_entity", "identity", "kyc", "aml_screening", "risk_rating", "pep" ], "additionalProperties": false }, "description": "The applicants, co-applicants, and guarantors, and the state of each check on them." }, "consents": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The party." }, "scope": { "type": "string", "description": "What the consent authorizes, e.g. `credit_pull`." }, "status": { "type": "string", "description": "`missing`, `active`, `expired`, or `revoked`." }, "consent_id": { "nullable": true, "description": "The consent record. Read it with `GET /deals/{id}/consents`. Null while it is missing.", "type": "string" }, "granted_at": { "nullable": true, "description": "When it was given.", "type": "string" }, "expires_at": { "nullable": true, "description": "When it lapses.", "type": "string" } }, "required": [ "contact_id", "scope", "status", "consent_id", "granted_at", "expires_at" ], "additionalProperties": false }, "description": "One entry for each party and each consent scope that the deal needs." }, "suitability": { "type": "object", "properties": { "status": { "type": "string", "description": "`missing`, `draft`, `attested`, or `stale`." }, "attested_at": { "nullable": true, "description": "When the broker attested it.", "type": "string" }, "attested_by_name": { "nullable": true, "description": "The broker who attested it.", "type": "string" }, "updated_at": { "nullable": true, "description": "Last change to the answers.", "type": "string" }, "custom_form": { "type": "boolean", "description": "True when the brokerage uses its own questions. False for the BrokerPlus questions." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "description": "The question." }, "question": { "type": "string", "description": "The question, as the form asks it." }, "answer": { "nullable": true, "description": "The answer as stored. Null when the question has no answer.", "type": "string" }, "answer_label": { "nullable": true, "description": "The answer as the form shows it.", "type": "string" } }, "required": [ "question_id", "question", "answer", "answer_label" ], "additionalProperties": false }, "description": "One entry for each question on the form, in form order." } }, "required": [ "status", "attested_at", "attested_by_name", "updated_at", "custom_form", "answers" ], "additionalProperties": false, "description": "The suitability assessment, on the suitability form of the brokerage." }, "document_requirements": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The requirement." }, "title": { "type": "string", "description": "The name of the document, for display." }, "checkpoint": { "type": "string", "description": "The checkpoint the document is due by." }, "status": { "type": "string", "description": "The state of the document, e.g. `missing`, `delivered`, or `signed`." }, "applicable": { "type": "boolean", "description": "False when the requirement does not apply to this deal." }, "satisfied": { "type": "boolean", "description": "True when the requirement is met." }, "enforcement": { "type": "string", "description": "`blocking` holds the checkpoint. `guidance` does not." }, "due_at": { "nullable": true, "description": "When it is due.", "type": "string" }, "custom_obligation_id": { "nullable": true, "description": "Set on a requirement the brokerage added to the deal. Upload evidence for it with `POST /deals/{id}/compliance/custom-obligations/{obligationId}/documents`. Null on a built-in requirement.", "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "The document. Read it with `GET /documents/{id}`." }, "file_name": { "type": "string", "description": "The file name." }, "linked_at": { "type": "string", "description": "When the document was attached to the requirement." } }, "required": [ "document_id", "file_name", "linked_at" ], "additionalProperties": false }, "description": "The documents that answered the requirement: an upload, a client's upload, or a signed copy." } }, "required": [ "key", "title", "checkpoint", "status", "applicable", "satisfied", "enforcement", "due_at", "custom_obligation_id", "evidence" ], "additionalProperties": false }, "description": "The disclosures and forms that the deal needs." }, "legal_hold": { "type": "boolean", "description": "True when a legal hold keeps the records of the deal from deletion." } }, "required": [ "object", "deal_id", "checkpoints", "blockers", "parties", "consents", "suitability", "document_requirements", "legal_hold" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/commitments": { "get": { "operationId": "listDealCommitments", "summary": "List a deal's lender commitments", "description": "The terms BrokerPlus read from the lender's commitment PDF, newest first, with the broker's corrections applied and the cost of borrowing worked out from them. Only a reviewed commitment goes on the cost of borrowing disclosure. Rates are PERCENT (`5.24` means 5.24%).", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "deal_commitment", "description": "The type of this record. Always `deal_commitment`.", "type": "string", "enum": [ "deal_commitment" ] }, "id": { "type": "string", "description": "Stable identifier for the commitment." }, "deal_id": { "type": "string", "description": "The deal the commitment is for." }, "source": { "type": "string", "enum": [ "lender_decision", "broker_upload" ], "description": "Where the commitment came from: `lender_decision` from the PDF the lender sent with its decision, `broker_upload` from a document on the deal." }, "source_label": { "type": "string", "description": "A name for the PDF the terms were read from, for display." }, "decision_id": { "nullable": true, "description": "The lender decision that carried the PDF. Null for an upload.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document the terms were read from. Null for a lender PDF.", "type": "string" }, "extracted_at": { "type": "string", "description": "When BrokerPlus read the terms from the PDF." }, "reviewed_at": { "nullable": true, "description": "When the broker reviewed the terms. Null until then. Only reviewed terms go on a disclosure a client signs.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who reviewed the terms. Null until then.", "type": "string" }, "terms": { "type": "object", "properties": { "lender_name": { "nullable": true, "description": "The lender, as the commitment names it.", "type": "string" }, "borrower_names": { "nullable": true, "description": "The borrowers, as the commitment names them.", "type": "string" }, "property_address": { "nullable": true, "description": "The property, as the commitment states it.", "type": "string" }, "commitment_date": { "nullable": true, "description": "The date of the commitment, as the commitment states it.", "type": "string" }, "principal": { "nullable": true, "description": "The amount of the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "The annual rate, as a PERCENT, e.g. `5.24` means 5.24%. Not a fraction.", "type": "number" }, "rate_type": { "nullable": true, "description": "The kind of rate.", "type": "string", "enum": [ "fixed", "variable", "adjustable", "arm" ] }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "number" }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "number" }, "payment_amount": { "nullable": true, "description": "The regular payment, in dollars.", "type": "number" }, "payment_frequency": { "nullable": true, "description": "How often the payment is made.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "first_payment_date": { "nullable": true, "description": "The first payment date, as the commitment states it.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "The interest adjustment date, as the commitment states it.", "type": "string" }, "maturity_date": { "nullable": true, "description": "The maturity date, as the commitment states it.", "type": "string" }, "net_advance": { "nullable": true, "description": "The amount advanced after deductions, in dollars.", "type": "number" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The name of the fee." }, "amount": { "type": "number", "description": "The amount, in dollars." }, "included_in_cost_of_borrowing": { "type": "boolean", "description": "True when the fee counts toward the annual percentage rate." }, "exclusion_reason": { "nullable": true, "description": "Why the fee does not count. Null when it counts.", "type": "string" }, "origin": { "type": "string", "enum": [ "commitment", "deal" ], "description": "`commitment` when read from the PDF, `deal` when the broker entered it on the deal's offer." } }, "required": [ "label", "amount", "included_in_cost_of_borrowing", "exclusion_reason", "origin" ], "additionalProperties": false }, "description": "The fees from the commitment, and the fees the broker entered on the deal's offer." }, "deal_fees": { "type": "string", "enum": [ "not_consulted", "consulted", "undetermined" ], "description": "Whether the fees on the deal were read: `consulted` they were, `undetermined` the deal has more than one offer so none were read, `not_consulted` only the commitment was read." }, "disclosed_cost_of_borrowing": { "nullable": true, "description": "The total cost of borrowing as the lender printed it, in dollars. Null when not stated.", "type": "number" }, "balance_at_maturity": { "nullable": true, "description": "The balance at the end of the term, in dollars.", "type": "number" }, "prepayment_privileges": { "nullable": true, "description": "What the borrower may prepay without a charge.", "type": "string" }, "prepayment_penalty_terms": { "nullable": true, "description": "How a prepayment charge is worked out.", "type": "string" }, "portability_terms": { "nullable": true, "description": "Whether and how the mortgage moves to another property.", "type": "string" }, "assumability_terms": { "nullable": true, "description": "Whether and how a buyer can take over the mortgage.", "type": "string" }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source_label": { "type": "string", "description": "The PDF or profile the value came from." }, "page": { "nullable": true, "description": "The page of the PDF, from 1. Null when not known.", "type": "number" } }, "required": [ "source_label", "page" ], "additionalProperties": false }, "description": "Where each value was read, keyed by the field name in `terms`. A value the broker corrected keeps the page it was first read from." } }, "required": [ "lender_name", "borrower_names", "property_address", "commitment_date", "principal", "interest_rate", "rate_type", "term_months", "amortization_months", "payment_amount", "payment_frequency", "first_payment_date", "interest_adjustment_date", "maturity_date", "net_advance", "fees", "deal_fees", "disclosed_cost_of_borrowing", "balance_at_maturity", "prepayment_privileges", "prepayment_penalty_terms", "portability_terms", "assumability_terms", "sources" ], "additionalProperties": false, "description": "The terms, with the broker's corrections applied. A value the commitment does not state is null: BrokerPlus never guesses one." }, "cost_of_borrowing": { "type": "object", "properties": { "apr": { "nullable": true, "description": "The annual percentage rate, as a PERCENT. Null when a value it needs is missing.", "type": "number" }, "computed_cost_of_borrowing": { "nullable": true, "description": "The cost of borrowing over the term, in dollars. Null when `apr` is null.", "type": "number" }, "included_fee_total": { "type": "number", "description": "The total of the fees that count toward the rate, in dollars." }, "missing_for_apr": { "type": "array", "items": { "type": "string" }, "description": "The values the commitment does not state that the rate needs." } }, "required": [ "apr", "computed_cost_of_borrowing", "included_fee_total", "missing_for_apr" ], "additionalProperties": false, "description": "The cost of borrowing BrokerPlus works out from the terms, for the disclosure." }, "created_at": { "type": "string", "description": "When the commitment was first read." }, "updated_at": { "type": "string", "description": "When the commitment last changed." } }, "required": [ "object", "id", "deal_id", "source", "source_label", "decision_id", "document_id", "extracted_at", "reviewed_at", "reviewed_by_user_id", "terms", "cost_of_borrowing", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "readDealCommitment", "summary": "Read the terms of a lender commitment", "description": "Reads the terms from the commitment PDF. With no body, BrokerPlus reads the PDF the lender sent with its latest decision. For a lender that sends none, upload the commitment as a document and send its id in `document_id`. Reading the same PDF again replaces its terms and clears the review. The terms are not on a disclosure until the broker reviews them. Nothing is sent.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "description": "A document on the deal that is a mortgage commitment. Leave it out to read the PDF the lender sent with its decision.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_commitment", "description": "The type of this record. Always `deal_commitment`.", "type": "string", "enum": [ "deal_commitment" ] }, "id": { "type": "string", "description": "Stable identifier for the commitment." }, "deal_id": { "type": "string", "description": "The deal the commitment is for." }, "source": { "type": "string", "enum": [ "lender_decision", "broker_upload" ], "description": "Where the commitment came from: `lender_decision` from the PDF the lender sent with its decision, `broker_upload` from a document on the deal." }, "source_label": { "type": "string", "description": "A name for the PDF the terms were read from, for display." }, "decision_id": { "nullable": true, "description": "The lender decision that carried the PDF. Null for an upload.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document the terms were read from. Null for a lender PDF.", "type": "string" }, "extracted_at": { "type": "string", "description": "When BrokerPlus read the terms from the PDF." }, "reviewed_at": { "nullable": true, "description": "When the broker reviewed the terms. Null until then. Only reviewed terms go on a disclosure a client signs.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who reviewed the terms. Null until then.", "type": "string" }, "terms": { "type": "object", "properties": { "lender_name": { "nullable": true, "description": "The lender, as the commitment names it.", "type": "string" }, "borrower_names": { "nullable": true, "description": "The borrowers, as the commitment names them.", "type": "string" }, "property_address": { "nullable": true, "description": "The property, as the commitment states it.", "type": "string" }, "commitment_date": { "nullable": true, "description": "The date of the commitment, as the commitment states it.", "type": "string" }, "principal": { "nullable": true, "description": "The amount of the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "The annual rate, as a PERCENT, e.g. `5.24` means 5.24%. Not a fraction.", "type": "number" }, "rate_type": { "nullable": true, "description": "The kind of rate.", "type": "string", "enum": [ "fixed", "variable", "adjustable", "arm" ] }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "number" }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "number" }, "payment_amount": { "nullable": true, "description": "The regular payment, in dollars.", "type": "number" }, "payment_frequency": { "nullable": true, "description": "How often the payment is made.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "first_payment_date": { "nullable": true, "description": "The first payment date, as the commitment states it.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "The interest adjustment date, as the commitment states it.", "type": "string" }, "maturity_date": { "nullable": true, "description": "The maturity date, as the commitment states it.", "type": "string" }, "net_advance": { "nullable": true, "description": "The amount advanced after deductions, in dollars.", "type": "number" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The name of the fee." }, "amount": { "type": "number", "description": "The amount, in dollars." }, "included_in_cost_of_borrowing": { "type": "boolean", "description": "True when the fee counts toward the annual percentage rate." }, "exclusion_reason": { "nullable": true, "description": "Why the fee does not count. Null when it counts.", "type": "string" }, "origin": { "type": "string", "enum": [ "commitment", "deal" ], "description": "`commitment` when read from the PDF, `deal` when the broker entered it on the deal's offer." } }, "required": [ "label", "amount", "included_in_cost_of_borrowing", "exclusion_reason", "origin" ], "additionalProperties": false }, "description": "The fees from the commitment, and the fees the broker entered on the deal's offer." }, "deal_fees": { "type": "string", "enum": [ "not_consulted", "consulted", "undetermined" ], "description": "Whether the fees on the deal were read: `consulted` they were, `undetermined` the deal has more than one offer so none were read, `not_consulted` only the commitment was read." }, "disclosed_cost_of_borrowing": { "nullable": true, "description": "The total cost of borrowing as the lender printed it, in dollars. Null when not stated.", "type": "number" }, "balance_at_maturity": { "nullable": true, "description": "The balance at the end of the term, in dollars.", "type": "number" }, "prepayment_privileges": { "nullable": true, "description": "What the borrower may prepay without a charge.", "type": "string" }, "prepayment_penalty_terms": { "nullable": true, "description": "How a prepayment charge is worked out.", "type": "string" }, "portability_terms": { "nullable": true, "description": "Whether and how the mortgage moves to another property.", "type": "string" }, "assumability_terms": { "nullable": true, "description": "Whether and how a buyer can take over the mortgage.", "type": "string" }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source_label": { "type": "string", "description": "The PDF or profile the value came from." }, "page": { "nullable": true, "description": "The page of the PDF, from 1. Null when not known.", "type": "number" } }, "required": [ "source_label", "page" ], "additionalProperties": false }, "description": "Where each value was read, keyed by the field name in `terms`. A value the broker corrected keeps the page it was first read from." } }, "required": [ "lender_name", "borrower_names", "property_address", "commitment_date", "principal", "interest_rate", "rate_type", "term_months", "amortization_months", "payment_amount", "payment_frequency", "first_payment_date", "interest_adjustment_date", "maturity_date", "net_advance", "fees", "deal_fees", "disclosed_cost_of_borrowing", "balance_at_maturity", "prepayment_privileges", "prepayment_penalty_terms", "portability_terms", "assumability_terms", "sources" ], "additionalProperties": false, "description": "The terms, with the broker's corrections applied. A value the commitment does not state is null: BrokerPlus never guesses one." }, "cost_of_borrowing": { "type": "object", "properties": { "apr": { "nullable": true, "description": "The annual percentage rate, as a PERCENT. Null when a value it needs is missing.", "type": "number" }, "computed_cost_of_borrowing": { "nullable": true, "description": "The cost of borrowing over the term, in dollars. Null when `apr` is null.", "type": "number" }, "included_fee_total": { "type": "number", "description": "The total of the fees that count toward the rate, in dollars." }, "missing_for_apr": { "type": "array", "items": { "type": "string" }, "description": "The values the commitment does not state that the rate needs." } }, "required": [ "apr", "computed_cost_of_borrowing", "included_fee_total", "missing_for_apr" ], "additionalProperties": false, "description": "The cost of borrowing BrokerPlus works out from the terms, for the disclosure." }, "created_at": { "type": "string", "description": "When the commitment was first read." }, "updated_at": { "type": "string", "description": "When the commitment last changed." } }, "required": [ "object", "id", "deal_id", "source", "source_label", "decision_id", "document_id", "extracted_at", "reviewed_at", "reviewed_by_user_id", "terms", "cost_of_borrowing", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The document is not classified as a mortgage commitment (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The lender sent no commitment PDF and no `document_id` was given (NO_COMMITMENT), or the document is not on the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/commitments/{commitmentId}": { "get": { "operationId": "getDealCommitment", "summary": "Retrieve a lender commitment", "description": "One commitment on the deal, with its terms and the cost of borrowing.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "commitmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_commitment", "description": "The type of this record. Always `deal_commitment`.", "type": "string", "enum": [ "deal_commitment" ] }, "id": { "type": "string", "description": "Stable identifier for the commitment." }, "deal_id": { "type": "string", "description": "The deal the commitment is for." }, "source": { "type": "string", "enum": [ "lender_decision", "broker_upload" ], "description": "Where the commitment came from: `lender_decision` from the PDF the lender sent with its decision, `broker_upload` from a document on the deal." }, "source_label": { "type": "string", "description": "A name for the PDF the terms were read from, for display." }, "decision_id": { "nullable": true, "description": "The lender decision that carried the PDF. Null for an upload.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document the terms were read from. Null for a lender PDF.", "type": "string" }, "extracted_at": { "type": "string", "description": "When BrokerPlus read the terms from the PDF." }, "reviewed_at": { "nullable": true, "description": "When the broker reviewed the terms. Null until then. Only reviewed terms go on a disclosure a client signs.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who reviewed the terms. Null until then.", "type": "string" }, "terms": { "type": "object", "properties": { "lender_name": { "nullable": true, "description": "The lender, as the commitment names it.", "type": "string" }, "borrower_names": { "nullable": true, "description": "The borrowers, as the commitment names them.", "type": "string" }, "property_address": { "nullable": true, "description": "The property, as the commitment states it.", "type": "string" }, "commitment_date": { "nullable": true, "description": "The date of the commitment, as the commitment states it.", "type": "string" }, "principal": { "nullable": true, "description": "The amount of the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "The annual rate, as a PERCENT, e.g. `5.24` means 5.24%. Not a fraction.", "type": "number" }, "rate_type": { "nullable": true, "description": "The kind of rate.", "type": "string", "enum": [ "fixed", "variable", "adjustable", "arm" ] }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "number" }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "number" }, "payment_amount": { "nullable": true, "description": "The regular payment, in dollars.", "type": "number" }, "payment_frequency": { "nullable": true, "description": "How often the payment is made.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "first_payment_date": { "nullable": true, "description": "The first payment date, as the commitment states it.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "The interest adjustment date, as the commitment states it.", "type": "string" }, "maturity_date": { "nullable": true, "description": "The maturity date, as the commitment states it.", "type": "string" }, "net_advance": { "nullable": true, "description": "The amount advanced after deductions, in dollars.", "type": "number" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The name of the fee." }, "amount": { "type": "number", "description": "The amount, in dollars." }, "included_in_cost_of_borrowing": { "type": "boolean", "description": "True when the fee counts toward the annual percentage rate." }, "exclusion_reason": { "nullable": true, "description": "Why the fee does not count. Null when it counts.", "type": "string" }, "origin": { "type": "string", "enum": [ "commitment", "deal" ], "description": "`commitment` when read from the PDF, `deal` when the broker entered it on the deal's offer." } }, "required": [ "label", "amount", "included_in_cost_of_borrowing", "exclusion_reason", "origin" ], "additionalProperties": false }, "description": "The fees from the commitment, and the fees the broker entered on the deal's offer." }, "deal_fees": { "type": "string", "enum": [ "not_consulted", "consulted", "undetermined" ], "description": "Whether the fees on the deal were read: `consulted` they were, `undetermined` the deal has more than one offer so none were read, `not_consulted` only the commitment was read." }, "disclosed_cost_of_borrowing": { "nullable": true, "description": "The total cost of borrowing as the lender printed it, in dollars. Null when not stated.", "type": "number" }, "balance_at_maturity": { "nullable": true, "description": "The balance at the end of the term, in dollars.", "type": "number" }, "prepayment_privileges": { "nullable": true, "description": "What the borrower may prepay without a charge.", "type": "string" }, "prepayment_penalty_terms": { "nullable": true, "description": "How a prepayment charge is worked out.", "type": "string" }, "portability_terms": { "nullable": true, "description": "Whether and how the mortgage moves to another property.", "type": "string" }, "assumability_terms": { "nullable": true, "description": "Whether and how a buyer can take over the mortgage.", "type": "string" }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source_label": { "type": "string", "description": "The PDF or profile the value came from." }, "page": { "nullable": true, "description": "The page of the PDF, from 1. Null when not known.", "type": "number" } }, "required": [ "source_label", "page" ], "additionalProperties": false }, "description": "Where each value was read, keyed by the field name in `terms`. A value the broker corrected keeps the page it was first read from." } }, "required": [ "lender_name", "borrower_names", "property_address", "commitment_date", "principal", "interest_rate", "rate_type", "term_months", "amortization_months", "payment_amount", "payment_frequency", "first_payment_date", "interest_adjustment_date", "maturity_date", "net_advance", "fees", "deal_fees", "disclosed_cost_of_borrowing", "balance_at_maturity", "prepayment_privileges", "prepayment_penalty_terms", "portability_terms", "assumability_terms", "sources" ], "additionalProperties": false, "description": "The terms, with the broker's corrections applied. A value the commitment does not state is null: BrokerPlus never guesses one." }, "cost_of_borrowing": { "type": "object", "properties": { "apr": { "nullable": true, "description": "The annual percentage rate, as a PERCENT. Null when a value it needs is missing.", "type": "number" }, "computed_cost_of_borrowing": { "nullable": true, "description": "The cost of borrowing over the term, in dollars. Null when `apr` is null.", "type": "number" }, "included_fee_total": { "type": "number", "description": "The total of the fees that count toward the rate, in dollars." }, "missing_for_apr": { "type": "array", "items": { "type": "string" }, "description": "The values the commitment does not state that the rate needs." } }, "required": [ "apr", "computed_cost_of_borrowing", "included_fee_total", "missing_for_apr" ], "additionalProperties": false, "description": "The cost of borrowing BrokerPlus works out from the terms, for the disclosure." }, "created_at": { "type": "string", "description": "When the commitment was first read." }, "updated_at": { "type": "string", "description": "When the commitment last changed." } }, "required": [ "object", "id", "deal_id", "source", "source_label", "decision_id", "document_id", "extracted_at", "reviewed_at", "reviewed_by_user_id", "terms", "cost_of_borrowing", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/commitments/{commitmentId}/review": { "post": { "operationId": "reviewDealCommitment", "summary": "Review a lender commitment", "description": "Marks the terms as reviewed by the broker, with any corrections in `edits`. A reviewed commitment is what the cost of borrowing disclosure prints, so review only terms the broker checked against the PDF. Corrections replace those of an earlier review. Nothing is sent.", "tags": [ "Mortgage" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "commitmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "edits": { "description": "Your corrections to what was read. They replace the corrections of an earlier review. Leave it out to accept the terms as read.", "type": "object", "properties": { "principal": { "description": "The amount of the mortgage, in dollars.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "interest_rate": { "description": "The annual rate, as a PERCENT, e.g. `5.24` means 5.24%.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "exclusiveMaximum": true }, "rate_type": { "description": "The kind of rate.", "nullable": true, "type": "string", "enum": [ "fixed", "variable", "adjustable", "arm" ] }, "term_months": { "description": "The term, in months.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "amortization_months": { "description": "The amortization, in months.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "payment_amount": { "description": "The regular payment, in dollars.", "nullable": true, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "payment_frequency": { "description": "How often the payment is made.", "nullable": true, "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "prepayment_privileges": { "description": "What may be prepaid.", "nullable": true, "type": "string", "maxLength": 4000 }, "prepayment_penalty_terms": { "description": "How a prepayment charge is worked out.", "nullable": true, "type": "string", "maxLength": 4000 }, "portability_terms": { "description": "Portability.", "nullable": true, "type": "string", "maxLength": 4000 }, "assumability_terms": { "description": "Assumability.", "nullable": true, "type": "string", "maxLength": 4000 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_commitment", "description": "The type of this record. Always `deal_commitment`.", "type": "string", "enum": [ "deal_commitment" ] }, "id": { "type": "string", "description": "Stable identifier for the commitment." }, "deal_id": { "type": "string", "description": "The deal the commitment is for." }, "source": { "type": "string", "enum": [ "lender_decision", "broker_upload" ], "description": "Where the commitment came from: `lender_decision` from the PDF the lender sent with its decision, `broker_upload` from a document on the deal." }, "source_label": { "type": "string", "description": "A name for the PDF the terms were read from, for display." }, "decision_id": { "nullable": true, "description": "The lender decision that carried the PDF. Null for an upload.", "type": "string" }, "document_id": { "nullable": true, "description": "The deal document the terms were read from. Null for a lender PDF.", "type": "string" }, "extracted_at": { "type": "string", "description": "When BrokerPlus read the terms from the PDF." }, "reviewed_at": { "nullable": true, "description": "When the broker reviewed the terms. Null until then. Only reviewed terms go on a disclosure a client signs.", "type": "string" }, "reviewed_by_user_id": { "nullable": true, "description": "The user who reviewed the terms. Null until then.", "type": "string" }, "terms": { "type": "object", "properties": { "lender_name": { "nullable": true, "description": "The lender, as the commitment names it.", "type": "string" }, "borrower_names": { "nullable": true, "description": "The borrowers, as the commitment names them.", "type": "string" }, "property_address": { "nullable": true, "description": "The property, as the commitment states it.", "type": "string" }, "commitment_date": { "nullable": true, "description": "The date of the commitment, as the commitment states it.", "type": "string" }, "principal": { "nullable": true, "description": "The amount of the mortgage, in dollars.", "type": "number" }, "interest_rate": { "nullable": true, "description": "The annual rate, as a PERCENT, e.g. `5.24` means 5.24%. Not a fraction.", "type": "number" }, "rate_type": { "nullable": true, "description": "The kind of rate.", "type": "string", "enum": [ "fixed", "variable", "adjustable", "arm" ] }, "term_months": { "nullable": true, "description": "The term, in months.", "type": "number" }, "amortization_months": { "nullable": true, "description": "The amortization, in months.", "type": "number" }, "payment_amount": { "nullable": true, "description": "The regular payment, in dollars.", "type": "number" }, "payment_frequency": { "nullable": true, "description": "How often the payment is made.", "type": "string", "enum": [ "monthly", "semi_monthly", "bi_weekly", "weekly", "accelerated_bi_weekly", "accelerated_weekly" ] }, "first_payment_date": { "nullable": true, "description": "The first payment date, as the commitment states it.", "type": "string" }, "interest_adjustment_date": { "nullable": true, "description": "The interest adjustment date, as the commitment states it.", "type": "string" }, "maturity_date": { "nullable": true, "description": "The maturity date, as the commitment states it.", "type": "string" }, "net_advance": { "nullable": true, "description": "The amount advanced after deductions, in dollars.", "type": "number" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The name of the fee." }, "amount": { "type": "number", "description": "The amount, in dollars." }, "included_in_cost_of_borrowing": { "type": "boolean", "description": "True when the fee counts toward the annual percentage rate." }, "exclusion_reason": { "nullable": true, "description": "Why the fee does not count. Null when it counts.", "type": "string" }, "origin": { "type": "string", "enum": [ "commitment", "deal" ], "description": "`commitment` when read from the PDF, `deal` when the broker entered it on the deal's offer." } }, "required": [ "label", "amount", "included_in_cost_of_borrowing", "exclusion_reason", "origin" ], "additionalProperties": false }, "description": "The fees from the commitment, and the fees the broker entered on the deal's offer." }, "deal_fees": { "type": "string", "enum": [ "not_consulted", "consulted", "undetermined" ], "description": "Whether the fees on the deal were read: `consulted` they were, `undetermined` the deal has more than one offer so none were read, `not_consulted` only the commitment was read." }, "disclosed_cost_of_borrowing": { "nullable": true, "description": "The total cost of borrowing as the lender printed it, in dollars. Null when not stated.", "type": "number" }, "balance_at_maturity": { "nullable": true, "description": "The balance at the end of the term, in dollars.", "type": "number" }, "prepayment_privileges": { "nullable": true, "description": "What the borrower may prepay without a charge.", "type": "string" }, "prepayment_penalty_terms": { "nullable": true, "description": "How a prepayment charge is worked out.", "type": "string" }, "portability_terms": { "nullable": true, "description": "Whether and how the mortgage moves to another property.", "type": "string" }, "assumability_terms": { "nullable": true, "description": "Whether and how a buyer can take over the mortgage.", "type": "string" }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source_label": { "type": "string", "description": "The PDF or profile the value came from." }, "page": { "nullable": true, "description": "The page of the PDF, from 1. Null when not known.", "type": "number" } }, "required": [ "source_label", "page" ], "additionalProperties": false }, "description": "Where each value was read, keyed by the field name in `terms`. A value the broker corrected keeps the page it was first read from." } }, "required": [ "lender_name", "borrower_names", "property_address", "commitment_date", "principal", "interest_rate", "rate_type", "term_months", "amortization_months", "payment_amount", "payment_frequency", "first_payment_date", "interest_adjustment_date", "maturity_date", "net_advance", "fees", "deal_fees", "disclosed_cost_of_borrowing", "balance_at_maturity", "prepayment_privileges", "prepayment_penalty_terms", "portability_terms", "assumability_terms", "sources" ], "additionalProperties": false, "description": "The terms, with the broker's corrections applied. A value the commitment does not state is null: BrokerPlus never guesses one." }, "cost_of_borrowing": { "type": "object", "properties": { "apr": { "nullable": true, "description": "The annual percentage rate, as a PERCENT. Null when a value it needs is missing.", "type": "number" }, "computed_cost_of_borrowing": { "nullable": true, "description": "The cost of borrowing over the term, in dollars. Null when `apr` is null.", "type": "number" }, "included_fee_total": { "type": "number", "description": "The total of the fees that count toward the rate, in dollars." }, "missing_for_apr": { "type": "array", "items": { "type": "string" }, "description": "The values the commitment does not state that the rate needs." } }, "required": [ "apr", "computed_cost_of_borrowing", "included_fee_total", "missing_for_apr" ], "additionalProperties": false, "description": "The cost of borrowing BrokerPlus works out from the terms, for the disclosure." }, "created_at": { "type": "string", "description": "When the commitment was first read." }, "updated_at": { "type": "string", "description": "When the commitment last changed." } }, "required": [ "object", "id", "deal_id", "source", "source_label", "decision_id", "document_id", "extracted_at", "reviewed_at", "reviewed_by_user_id", "terms", "cost_of_borrowing", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/credit-reports": { "get": { "operationId": "listDealCreditReports", "summary": "List a deal's credit reports", "description": "The credit reports on the deal, newest first: the score, the bureau, when BrokerPlus got the report, and the account totals that the deal shows. The report itself, its accounts, and the account numbers are not published. The API cannot pull credit: the broker does that in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "credit_report", "description": "The type of this record. Always `credit_report`.", "type": "string", "enum": [ "credit_report" ] }, "id": { "type": "string", "description": "Stable identifier for the credit report." }, "deal_id": { "type": "string", "description": "The deal it was pulled on." }, "contact_id": { "type": "string", "description": "The party it is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "nullable": true, "description": "The party's name, for display.", "type": "string" }, "bureau": { "type": "string", "description": "The credit bureau, or the system the report came from, e.g. `Equifax`." }, "status": { "type": "string", "enum": [ "pending", "complete", "no_hit", "error", "no_score" ], "description": "`complete` has a result. `no_hit` means the bureau has no file. `pending` waits, and `error` failed. `no_score` is a check the system the deal came from ran, which returned no score." }, "score": { "nullable": true, "description": "The credit score. Null when there is none.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "joint_score": { "nullable": true, "description": "The joint score, on a joint report. Null otherwise.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "no_hit": { "type": "boolean", "description": "True when the bureau found no file for the party." }, "report_date": { "nullable": true, "description": "The date of the report at the bureau, as `YYYY-MM-DD`.", "type": "string" }, "pulled_at": { "type": "string", "description": "When BrokerPlus got the report." }, "requested_by_user_id": { "nullable": true, "description": "The broker who pulled it. Null for an imported report.", "type": "string" }, "consent_id": { "nullable": true, "description": "The `credit_pull` consent that authorized the pull. Read it with `GET /deals/{id}/consents`.", "type": "string" }, "detail_pending": { "type": "boolean", "description": "True when only the score is known. Each total in `tradeline_summary` is then null." }, "tradeline_summary": { "type": "object", "properties": { "total_trades": { "nullable": true, "description": "All accounts on the report.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "open_trades": { "nullable": true, "description": "Accounts that are open.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "delinquent_trades": { "nullable": true, "description": "Accounts that are past due or derogatory.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_balance": { "nullable": true, "description": "The sum of the balances, in dollars.", "type": "number" }, "total_credit_limit": { "nullable": true, "description": "The sum of the credit limits, in dollars.", "type": "number" }, "utilization": { "nullable": true, "description": "The balances as a percent of the limits, e.g. `42.5`.", "type": "number" }, "collections_count": { "nullable": true, "description": "Accounts in collection.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "public_records_count": { "nullable": true, "description": "Bankruptcies, judgments, and liens.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inquiries_6_months": { "nullable": true, "description": "Credit inquiries in the last six months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oldest_trade_months": { "nullable": true, "description": "The age of the oldest account, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total_trades", "open_trades", "delinquent_trades", "total_balance", "total_credit_limit", "utilization", "collections_count", "public_records_count", "inquiries_6_months", "oldest_trade_months" ], "additionalProperties": false, "description": "The totals that the deal shows. Each total is null when the report does not give it. The accounts themselves and their numbers are not published." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "bureau", "status", "score", "joint_score", "no_hit", "report_date", "pulled_at", "requested_by_user_id", "consent_id", "detail_pending", "tradeline_summary", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/package-requirements": { "get": { "operationId": "listCompliancePackageRequirements", "summary": "List the requirements a package slot can use", "description": "The requirements that a compliance package template can put in a slot: the built-in disclosures and the brokerage's own requirements. Put the `key` in `requirement_key`. A team template can use a requirement of its team. A brokerage template can use only a `brokerage_wide` requirement.", "tags": [ "Compliance" ], "parameters": [ { "name": "team_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the requirements that a template of this team can use. Without it, the list has the requirements of every team the broker can change." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The key to put in `requirement_key` on a slot." }, "title": { "type": "string", "description": "The name of the requirement." }, "summary": { "type": "string", "description": "What the requirement asks for." }, "brokerage_wide": { "type": "boolean", "description": "The requirement applies to every team. Only a brokerage-wide requirement can go in a brokerage template." } }, "required": [ "key", "title", "summary", "brokerage_wide" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/package-templates": { "get": { "operationId": "listCompliancePackageTemplates", "summary": "List compliance package templates", "description": "The layouts that a deal's compliance package is built from, as the compliance hub shows them: the brokerage's templates first, then the templates of the teams the broker is on. An archived template is not listed.", "tags": [ "Compliance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "team", "brokerage" ] }, "description": "Only `team` templates or only `brokerage` templates." }, { "name": "team_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the templates of this team." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_template", "description": "The type of this record. Always `compliance_package_template`.", "type": "string", "enum": [ "compliance_package_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "owner": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` for a team's own template. `brokerage` for a template that the brokerage sets for every team. Only a compliance administrator can change a brokerage template." }, "team_id": { "nullable": true, "description": "The team that owns the template. Null for a brokerage template.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of the team, for display. Null for a brokerage template.", "type": "string" }, "name": { "type": "string", "description": "The name of the template." }, "description": { "nullable": true, "description": "What the template is for. Null if not set.", "type": "string" }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_template_slot", "description": "The type of this record. Always `compliance_package_template_slot`.", "type": "string", "enum": [ "compliance_package_template_slot" ] }, "id": { "type": "string", "description": "Stable identifier for the slot." }, "requirement_key": { "type": "string", "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "description": "The name of the slot in the package and on its cover page." }, "required": { "type": "boolean", "description": "A package cannot be built while a required slot has no document or is left out." }, "included": { "type": "boolean", "description": "The slot is in the package. A slot that is not included is skipped." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. An older document is flagged as stale. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "owner", "team_id", "team_name", "name", "description", "include_cover", "cover_title", "cover_message", "slots", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "`team_id` is sent with `owner=brokerage`, or a query value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createCompliancePackageTemplate", "summary": "Create a compliance package template", "description": "Makes a package template for a team, or for the brokerage when `team_id` is null. The broker must be able to change the team. Only a compliance administrator can make a brokerage template. A template only sets the layout of a package: it does not change what a deal must have.", "tags": [ "Compliance" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "nullable": true, "description": "The team that owns the template. Null for a brokerage template, which only a compliance administrator can make. Find the team ids with `GET /v1/teams`.", "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name of the template. It must be unique for its owner." }, "description": { "default": null, "description": "What the template is for.", "nullable": true, "type": "string", "maxLength": 2000 }, "include_cover": { "default": true, "description": "The package starts with a cover page. Default `true`.", "type": "boolean" }, "cover_title": { "default": "Compliance package", "description": "The title on the cover page. Default `Compliance package`.", "type": "string", "minLength": 1, "maxLength": 300 }, "cover_message": { "default": null, "description": "The message on the cover page.", "nullable": true, "type": "string", "maxLength": 4000 }, "slots": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "requirement_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The name of the slot in the package." }, "required": { "default": true, "description": "A package cannot be built while a required slot has no document or is left out. Default `true`.", "type": "boolean" }, "included": { "default": true, "description": "The slot is in the package. Default `true`.", "type": "boolean" }, "max_age_days": { "default": null, "description": "The oldest that the document can be, in days. Null or not set for no limit.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package. Each requirement and each position can be used one time. This replaces all the slots." } }, "required": [ "team_id", "name", "description", "include_cover", "cover_title", "cover_message", "slots" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package_template", "description": "The type of this record. Always `compliance_package_template`.", "type": "string", "enum": [ "compliance_package_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "owner": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` for a team's own template. `brokerage` for a template that the brokerage sets for every team. Only a compliance administrator can change a brokerage template." }, "team_id": { "nullable": true, "description": "The team that owns the template. Null for a brokerage template.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of the team, for display. Null for a brokerage template.", "type": "string" }, "name": { "type": "string", "description": "The name of the template." }, "description": { "nullable": true, "description": "What the template is for. Null if not set.", "type": "string" }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_template_slot", "description": "The type of this record. Always `compliance_package_template_slot`.", "type": "string", "enum": [ "compliance_package_template_slot" ] }, "id": { "type": "string", "description": "Stable identifier for the slot." }, "requirement_key": { "type": "string", "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "description": "The name of the slot in the package and on its cover page." }, "required": { "type": "boolean", "description": "A package cannot be built while a required slot has no document or is left out." }, "included": { "type": "boolean", "description": "The slot is in the package. A slot that is not included is skipped." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. An older document is flagged as stale. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "owner", "team_id", "team_name", "name", "description", "include_cover", "cover_title", "cover_message", "slots", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A slot names a requirement that the owner cannot use, or repeats a requirement or a position (VALIDATION_ERROR, INVALID_REQUIREMENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change the team, the brokerage locked team templates, or a brokerage template is asked for by a broker who is not a compliance administrator (TEAM_NOT_WRITABLE, BLOCKED_BY_BROKERAGE, FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The team does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The owner already has a template with this name (DUPLICATE_TEMPLATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/package-templates/{id}": { "get": { "operationId": "getCompliancePackageTemplate", "summary": "Retrieve a compliance package template", "description": "One compliance package template, with its slots in order.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package_template", "description": "The type of this record. Always `compliance_package_template`.", "type": "string", "enum": [ "compliance_package_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "owner": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` for a team's own template. `brokerage` for a template that the brokerage sets for every team. Only a compliance administrator can change a brokerage template." }, "team_id": { "nullable": true, "description": "The team that owns the template. Null for a brokerage template.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of the team, for display. Null for a brokerage template.", "type": "string" }, "name": { "type": "string", "description": "The name of the template." }, "description": { "nullable": true, "description": "What the template is for. Null if not set.", "type": "string" }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_template_slot", "description": "The type of this record. Always `compliance_package_template_slot`.", "type": "string", "enum": [ "compliance_package_template_slot" ] }, "id": { "type": "string", "description": "Stable identifier for the slot." }, "requirement_key": { "type": "string", "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "description": "The name of the slot in the package and on its cover page." }, "required": { "type": "boolean", "description": "A package cannot be built while a required slot has no document or is left out." }, "included": { "type": "boolean", "description": "The slot is in the package. A slot that is not included is skipped." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. An older document is flagged as stale. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "owner", "team_id", "team_name", "name", "description", "include_cover", "cover_title", "cover_message", "slots", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No template the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateCompliancePackageTemplate", "summary": "Update a compliance package template", "description": "Changes the fields that you send. `slots` replaces all the slots. The owner of a template cannot change: make a new template. A package already on a deal keeps the layout it was made from.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name of the template. It must be unique for its owner." }, "description": { "nullable": true, "description": "What the template is for.", "type": "string", "maxLength": 2000 }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page.", "type": "string", "maxLength": 4000 }, "slots": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "requirement_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The name of the slot in the package." }, "required": { "default": true, "description": "A package cannot be built while a required slot has no document or is left out. Default `true`.", "type": "boolean" }, "included": { "default": true, "description": "The slot is in the package. Default `true`.", "type": "boolean" }, "max_age_days": { "default": null, "description": "The oldest that the document can be, in days. Null or not set for no limit.", "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package. Each requirement and each position can be used one time. This replaces all the slots." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package_template", "description": "The type of this record. Always `compliance_package_template`.", "type": "string", "enum": [ "compliance_package_template" ] }, "id": { "type": "string", "description": "Stable identifier for the template." }, "owner": { "type": "string", "enum": [ "team", "brokerage" ], "description": "`team` for a team's own template. `brokerage` for a template that the brokerage sets for every team. Only a compliance administrator can change a brokerage template." }, "team_id": { "nullable": true, "description": "The team that owns the template. Null for a brokerage template.", "type": "string" }, "team_name": { "nullable": true, "description": "The name of the team, for display. Null for a brokerage template.", "type": "string" }, "name": { "type": "string", "description": "The name of the template." }, "description": { "nullable": true, "description": "What the template is for. Null if not set.", "type": "string" }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_template_slot", "description": "The type of this record. Always `compliance_package_template_slot`.", "type": "string", "enum": [ "compliance_package_template_slot" ] }, "id": { "type": "string", "description": "Stable identifier for the slot." }, "requirement_key": { "type": "string", "description": "The requirement that fills this slot. Get the keys from `GET /v1/compliance/package-requirements`." }, "display_name": { "type": "string", "description": "The name of the slot in the package and on its cover page." }, "required": { "type": "boolean", "description": "A package cannot be built while a required slot has no document or is left out." }, "included": { "type": "boolean", "description": "The slot is in the package. A slot that is not included is skipped." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. An older document is flagged as stale. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the slot in the package, from 0." } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "created_at": { "type": "string", "description": "When the template was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "owner", "team_id", "team_name", "name", "description", "include_cover", "cover_title", "cover_message", "slots", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty, or a slot is not valid (VALIDATION_ERROR, INVALID_REQUIREMENT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change this template (TEAM_NOT_WRITABLE, BLOCKED_BY_BROKERAGE, FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No template the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The owner already has a template with this name (DUPLICATE_TEMPLATE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteCompliancePackageTemplate", "summary": "Archive a compliance package template", "description": "Archives the template, as the compliance hub does. It is no longer offered for a deal. A package already made from it stays on its deal.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker cannot change this template (TEAM_NOT_WRITABLE, BLOCKED_BY_BROKERAGE, FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No template the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The template changed while it was archived (TEMPLATE_CHANGED).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance/package": { "get": { "operationId": "getDealCompliancePackage", "summary": "Read a deal's compliance package", "description": "The compliance package of the deal: one PDF of the deal's documents, in the order of a template, for a lender or an auditor. It shows each item, what fills it, and the checks on the package. A deal with no package yet gets `404`: make one with `POST /deals/{id}/compliance/package`.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package", "description": "The type of this record. Always `compliance_package`.", "type": "string", "enum": [ "compliance_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "deal_id": { "type": "string", "description": "The deal that the package is for. A deal has at most one package." }, "template_id": { "nullable": true, "description": "The template that the package was made from. Null if that template is gone.", "type": "string" }, "template_owner": { "nullable": true, "description": "`team` or `brokerage`: who owns the template. Null if that template is gone.", "type": "string", "enum": [ "team", "brokerage" ] }, "template_name": { "type": "string", "description": "The name of the template when the package was made from it." }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "status": { "type": "string", "enum": [ "draft", "building", "ready", "failed" ], "description": "`draft` until it is built, `building` while it is built, `ready` when the PDF is there, `failed` when the build did not finish." }, "build_phase": { "nullable": true, "description": "The step of the build in progress. Null when no build is running.", "type": "string", "enum": [ "queued", "collecting", "converting", "cover", "merging", "uploading" ] }, "stale": { "type": "boolean", "description": "The package changed after its PDF was built. Build it again before you download it." }, "has_pdf": { "type": "boolean", "description": "A built PDF is there. Get a link to it with the download endpoint." }, "build_started_at": { "nullable": true, "description": "When the last build started. Null if never.", "type": "string" }, "built_at": { "nullable": true, "description": "When the last build finished. Null if never.", "type": "string" }, "failure_code": { "nullable": true, "description": "Why the last build failed. Null unless `status` is `failed`.", "type": "string" }, "failure_message": { "nullable": true, "description": "The failure in words. Null unless `status` is `failed`.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_item", "description": "The type of this record. Always `compliance_package_item`.", "type": "string", "enum": [ "compliance_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "requirement_key": { "type": "string", "description": "The requirement that the item fills, from the template slot." }, "display_name": { "type": "string", "description": "The name of the item in the package and on its cover page." }, "required": { "type": "boolean", "description": "The package cannot be built while this item has no document or is left out." }, "included": { "type": "boolean", "description": "The item is in the package. The broker can leave an item out." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package, from 0." }, "source_kind": { "type": "string", "enum": [ "document", "disclosure_artifact", "missing" ], "description": "What fills the item: `document` for a document on the deal, `disclosure_artifact` for a disclosure that BrokerPlus made, `missing` when the deal has nothing for it yet." }, "source_id": { "type": "string", "description": "The document id for `document`, the disclosure id for `disclosure_artifact`, and the requirement key for `missing`." }, "source_mime_type": { "nullable": true, "description": "The file type of the source. Null when nothing fills the item.", "type": "string" }, "source_updated_at": { "nullable": true, "description": "When the source last changed. Null when nothing fills the item.", "type": "string" }, "conversion_status": { "type": "string", "description": "Where the conversion of the source to PDF is: `pending` until a build converts it." }, "page_count": { "nullable": true, "description": "The pages that the item adds to the PDF. Null until it is built.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position", "source_kind", "source_id", "source_mime_type", "source_updated_at", "conversion_status", "page_count" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_required", "missing_optional", "required_excluded", "duplicate", "stale", "empty_package", "unsupported_source" ], "description": "What the check found." }, "severity": { "type": "string", "enum": [ "blocker", "warning", "info" ], "description": "A `blocker` stops the build. A `warning` or `info` does not." }, "title": { "type": "string", "description": "What is wrong, in one sentence." }, "remediation": { "type": "string", "description": "What to do about it." }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the finding is about." } }, "required": [ "code", "severity", "title", "remediation", "item_ids" ], "additionalProperties": false }, "description": "The checks on the package as it is now. A build is refused while a `blocker` is open." }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "template_id", "template_owner", "template_name", "include_cover", "cover_title", "cover_message", "status", "build_phase", "stale", "has_pdf", "build_started_at", "built_at", "failure_code", "failure_message", "items", "findings", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, the broker cannot read it, or it has no package (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "createDealCompliancePackage", "summary": "Make a deal's compliance package from a template", "description": "Makes the package of the deal from a template, and fills each item from the deal's documents and disclosures. If the deal already has a package, this makes it again from the template, and the changes to the old package are lost. The response is `201` for a new package and `200` for a package made again. Nothing is built or sent: build it with `POST /deals/{id}/compliance/package/build`.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "string", "minLength": 1, "description": "The template to build the package from: one of the deal's team, or a brokerage template. Find it with `GET /v1/compliance/package-templates?team_id=`. If the deal already has a package, this makes it again from this template and the broker's changes are lost." } }, "required": [ "template_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package", "description": "The type of this record. Always `compliance_package`.", "type": "string", "enum": [ "compliance_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "deal_id": { "type": "string", "description": "The deal that the package is for. A deal has at most one package." }, "template_id": { "nullable": true, "description": "The template that the package was made from. Null if that template is gone.", "type": "string" }, "template_owner": { "nullable": true, "description": "`team` or `brokerage`: who owns the template. Null if that template is gone.", "type": "string", "enum": [ "team", "brokerage" ] }, "template_name": { "type": "string", "description": "The name of the template when the package was made from it." }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "status": { "type": "string", "enum": [ "draft", "building", "ready", "failed" ], "description": "`draft` until it is built, `building` while it is built, `ready` when the PDF is there, `failed` when the build did not finish." }, "build_phase": { "nullable": true, "description": "The step of the build in progress. Null when no build is running.", "type": "string", "enum": [ "queued", "collecting", "converting", "cover", "merging", "uploading" ] }, "stale": { "type": "boolean", "description": "The package changed after its PDF was built. Build it again before you download it." }, "has_pdf": { "type": "boolean", "description": "A built PDF is there. Get a link to it with the download endpoint." }, "build_started_at": { "nullable": true, "description": "When the last build started. Null if never.", "type": "string" }, "built_at": { "nullable": true, "description": "When the last build finished. Null if never.", "type": "string" }, "failure_code": { "nullable": true, "description": "Why the last build failed. Null unless `status` is `failed`.", "type": "string" }, "failure_message": { "nullable": true, "description": "The failure in words. Null unless `status` is `failed`.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_item", "description": "The type of this record. Always `compliance_package_item`.", "type": "string", "enum": [ "compliance_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "requirement_key": { "type": "string", "description": "The requirement that the item fills, from the template slot." }, "display_name": { "type": "string", "description": "The name of the item in the package and on its cover page." }, "required": { "type": "boolean", "description": "The package cannot be built while this item has no document or is left out." }, "included": { "type": "boolean", "description": "The item is in the package. The broker can leave an item out." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package, from 0." }, "source_kind": { "type": "string", "enum": [ "document", "disclosure_artifact", "missing" ], "description": "What fills the item: `document` for a document on the deal, `disclosure_artifact` for a disclosure that BrokerPlus made, `missing` when the deal has nothing for it yet." }, "source_id": { "type": "string", "description": "The document id for `document`, the disclosure id for `disclosure_artifact`, and the requirement key for `missing`." }, "source_mime_type": { "nullable": true, "description": "The file type of the source. Null when nothing fills the item.", "type": "string" }, "source_updated_at": { "nullable": true, "description": "When the source last changed. Null when nothing fills the item.", "type": "string" }, "conversion_status": { "type": "string", "description": "Where the conversion of the source to PDF is: `pending` until a build converts it." }, "page_count": { "nullable": true, "description": "The pages that the item adds to the PDF. Null until it is built.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position", "source_kind", "source_id", "source_mime_type", "source_updated_at", "conversion_status", "page_count" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_required", "missing_optional", "required_excluded", "duplicate", "stale", "empty_package", "unsupported_source" ], "description": "What the check found." }, "severity": { "type": "string", "enum": [ "blocker", "warning", "info" ], "description": "A `blocker` stops the build. A `warning` or `info` does not." }, "title": { "type": "string", "description": "What is wrong, in one sentence." }, "remediation": { "type": "string", "description": "What to do about it." }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the finding is about." } }, "required": [ "code", "severity", "title", "remediation", "item_ids" ], "additionalProperties": false }, "description": "The checks on the package as it is now. A build is refused while a `blocker` is open." }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "template_id", "template_owner", "template_name", "include_cover", "cover_title", "cover_message", "status", "build_phase", "stale", "has_pdf", "build_started_at", "built_at", "failure_code", "failure_message", "items", "findings", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist or the broker cannot change it, or the template is not one of the deal's team or the brokerage (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The deal has no team, or a build is running (DEAL_NO_TEAM, PACKAGE_BUILDING).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealCompliancePackage", "summary": "Change a deal's compliance package", "description": "Changes the cover page, and the name, place, or inclusion of the items that you send. The package then needs a new build. Leaving out a required item does not remove the requirement: the build is refused until the item is in again.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_cover": { "description": "The package starts with a cover page.", "type": "boolean" }, "cover_title": { "description": "The title on the cover page.", "type": "string", "minLength": 1, "maxLength": 300 }, "cover_message": { "description": "The message on the cover page.", "nullable": true, "type": "string", "maxLength": 4000 }, "items": { "description": "The items to change. An item that you do not send stays as it is. Each position must be unique.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "The item to change." }, "display_name": { "description": "A new name for the item.", "type": "string", "minLength": 1, "maxLength": 300 }, "included": { "description": "Put the item in the package, or leave it out.", "type": "boolean" }, "position": { "description": "A new place for the item, from 0.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package", "description": "The type of this record. Always `compliance_package`.", "type": "string", "enum": [ "compliance_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "deal_id": { "type": "string", "description": "The deal that the package is for. A deal has at most one package." }, "template_id": { "nullable": true, "description": "The template that the package was made from. Null if that template is gone.", "type": "string" }, "template_owner": { "nullable": true, "description": "`team` or `brokerage`: who owns the template. Null if that template is gone.", "type": "string", "enum": [ "team", "brokerage" ] }, "template_name": { "type": "string", "description": "The name of the template when the package was made from it." }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "status": { "type": "string", "enum": [ "draft", "building", "ready", "failed" ], "description": "`draft` until it is built, `building` while it is built, `ready` when the PDF is there, `failed` when the build did not finish." }, "build_phase": { "nullable": true, "description": "The step of the build in progress. Null when no build is running.", "type": "string", "enum": [ "queued", "collecting", "converting", "cover", "merging", "uploading" ] }, "stale": { "type": "boolean", "description": "The package changed after its PDF was built. Build it again before you download it." }, "has_pdf": { "type": "boolean", "description": "A built PDF is there. Get a link to it with the download endpoint." }, "build_started_at": { "nullable": true, "description": "When the last build started. Null if never.", "type": "string" }, "built_at": { "nullable": true, "description": "When the last build finished. Null if never.", "type": "string" }, "failure_code": { "nullable": true, "description": "Why the last build failed. Null unless `status` is `failed`.", "type": "string" }, "failure_message": { "nullable": true, "description": "The failure in words. Null unless `status` is `failed`.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_item", "description": "The type of this record. Always `compliance_package_item`.", "type": "string", "enum": [ "compliance_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "requirement_key": { "type": "string", "description": "The requirement that the item fills, from the template slot." }, "display_name": { "type": "string", "description": "The name of the item in the package and on its cover page." }, "required": { "type": "boolean", "description": "The package cannot be built while this item has no document or is left out." }, "included": { "type": "boolean", "description": "The item is in the package. The broker can leave an item out." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package, from 0." }, "source_kind": { "type": "string", "enum": [ "document", "disclosure_artifact", "missing" ], "description": "What fills the item: `document` for a document on the deal, `disclosure_artifact` for a disclosure that BrokerPlus made, `missing` when the deal has nothing for it yet." }, "source_id": { "type": "string", "description": "The document id for `document`, the disclosure id for `disclosure_artifact`, and the requirement key for `missing`." }, "source_mime_type": { "nullable": true, "description": "The file type of the source. Null when nothing fills the item.", "type": "string" }, "source_updated_at": { "nullable": true, "description": "When the source last changed. Null when nothing fills the item.", "type": "string" }, "conversion_status": { "type": "string", "description": "Where the conversion of the source to PDF is: `pending` until a build converts it." }, "page_count": { "nullable": true, "description": "The pages that the item adds to the PDF. Null until it is built.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position", "source_kind", "source_id", "source_mime_type", "source_updated_at", "conversion_status", "page_count" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_required", "missing_optional", "required_excluded", "duplicate", "stale", "empty_package", "unsupported_source" ], "description": "What the check found." }, "severity": { "type": "string", "enum": [ "blocker", "warning", "info" ], "description": "A `blocker` stops the build. A `warning` or `info` does not." }, "title": { "type": "string", "description": "What is wrong, in one sentence." }, "remediation": { "type": "string", "description": "What to do about it." }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the finding is about." } }, "required": [ "code", "severity", "title", "remediation", "item_ids" ], "additionalProperties": false }, "description": "The checks on the package as it is now. A build is refused while a `blocker` is open." }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "template_id", "template_owner", "template_name", "include_cover", "cover_title", "cover_message", "status", "build_phase", "stale", "has_pdf", "build_started_at", "built_at", "failure_code", "failure_message", "items", "findings", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty, or two items get the same position (VALIDATION_ERROR, DUPLICATE_POSITION).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal, its package, or an item does not exist, or the broker cannot change it (NOT_FOUND, ITEM_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The deal has no team, or a build is running (DEAL_NO_TEAM, PACKAGE_BUILDING).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance/package/build": { "post": { "operationId": "buildDealCompliancePackage", "summary": "Build a deal's compliance package", "description": "Starts the build of the package into one PDF, and returns the package with `status` `building`. Read the package again to see when it is `ready`. The build is refused while a finding is a `blocker`: the details list the findings. Nothing is sent.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_package", "description": "The type of this record. Always `compliance_package`.", "type": "string", "enum": [ "compliance_package" ] }, "id": { "type": "string", "description": "Stable identifier for the package." }, "deal_id": { "type": "string", "description": "The deal that the package is for. A deal has at most one package." }, "template_id": { "nullable": true, "description": "The template that the package was made from. Null if that template is gone.", "type": "string" }, "template_owner": { "nullable": true, "description": "`team` or `brokerage`: who owns the template. Null if that template is gone.", "type": "string", "enum": [ "team", "brokerage" ] }, "template_name": { "type": "string", "description": "The name of the template when the package was made from it." }, "include_cover": { "type": "boolean", "description": "The package starts with a cover page." }, "cover_title": { "type": "string", "description": "The title on the cover page." }, "cover_message": { "nullable": true, "description": "The message on the cover page. Null for no message.", "type": "string" }, "status": { "type": "string", "enum": [ "draft", "building", "ready", "failed" ], "description": "`draft` until it is built, `building` while it is built, `ready` when the PDF is there, `failed` when the build did not finish." }, "build_phase": { "nullable": true, "description": "The step of the build in progress. Null when no build is running.", "type": "string", "enum": [ "queued", "collecting", "converting", "cover", "merging", "uploading" ] }, "stale": { "type": "boolean", "description": "The package changed after its PDF was built. Build it again before you download it." }, "has_pdf": { "type": "boolean", "description": "A built PDF is there. Get a link to it with the download endpoint." }, "build_started_at": { "nullable": true, "description": "When the last build started. Null if never.", "type": "string" }, "built_at": { "nullable": true, "description": "When the last build finished. Null if never.", "type": "string" }, "failure_code": { "nullable": true, "description": "Why the last build failed. Null unless `status` is `failed`.", "type": "string" }, "failure_message": { "nullable": true, "description": "The failure in words. Null unless `status` is `failed`.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_package_item", "description": "The type of this record. Always `compliance_package_item`.", "type": "string", "enum": [ "compliance_package_item" ] }, "id": { "type": "string", "description": "Stable identifier for the item." }, "requirement_key": { "type": "string", "description": "The requirement that the item fills, from the template slot." }, "display_name": { "type": "string", "description": "The name of the item in the package and on its cover page." }, "required": { "type": "boolean", "description": "The package cannot be built while this item has no document or is left out." }, "included": { "type": "boolean", "description": "The item is in the package. The broker can leave an item out." }, "max_age_days": { "nullable": true, "description": "The oldest that the document can be, in days. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The order of the item in the package, from 0." }, "source_kind": { "type": "string", "enum": [ "document", "disclosure_artifact", "missing" ], "description": "What fills the item: `document` for a document on the deal, `disclosure_artifact` for a disclosure that BrokerPlus made, `missing` when the deal has nothing for it yet." }, "source_id": { "type": "string", "description": "The document id for `document`, the disclosure id for `disclosure_artifact`, and the requirement key for `missing`." }, "source_mime_type": { "nullable": true, "description": "The file type of the source. Null when nothing fills the item.", "type": "string" }, "source_updated_at": { "nullable": true, "description": "When the source last changed. Null when nothing fills the item.", "type": "string" }, "conversion_status": { "type": "string", "description": "Where the conversion of the source to PDF is: `pending` until a build converts it." }, "page_count": { "nullable": true, "description": "The pages that the item adds to the PDF. Null until it is built.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "id", "requirement_key", "display_name", "required", "included", "max_age_days", "position", "source_kind", "source_id", "source_mime_type", "source_updated_at", "conversion_status", "page_count" ], "additionalProperties": false }, "description": "The documents in the package, in order." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_required", "missing_optional", "required_excluded", "duplicate", "stale", "empty_package", "unsupported_source" ], "description": "What the check found." }, "severity": { "type": "string", "enum": [ "blocker", "warning", "info" ], "description": "A `blocker` stops the build. A `warning` or `info` does not." }, "title": { "type": "string", "description": "What is wrong, in one sentence." }, "remediation": { "type": "string", "description": "What to do about it." }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the finding is about." } }, "required": [ "code", "severity", "title", "remediation", "item_ids" ], "additionalProperties": false }, "description": "The checks on the package as it is now. A build is refused while a `blocker` is open." }, "created_at": { "type": "string", "description": "When the package was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "template_id", "template_owner", "template_name", "include_cover", "cover_title", "cover_message", "status", "build_phase", "stale", "has_pdf", "build_started_at", "built_at", "failure_code", "failure_message", "items", "findings", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or its package does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "A build is running, the package has a blocker, or the deal has no team (PACKAGE_BUILDING, PACKAGE_BLOCKED, DEAL_NO_TEAM).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance/package/download": { "get": { "operationId": "downloadDealCompliancePackage", "summary": "Get a link to a deal's compliance package PDF", "description": "A signed link to the built PDF of the package. It works for five minutes. The link is refused while the package is not built, or changed after its build.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "package_id": { "type": "string", "description": "The package." }, "url": { "type": "string", "description": "A signed link to the PDF. It works for five minutes. Anybody who holds it can read the file." }, "file_name": { "type": "string", "description": "The name of the file." } }, "required": [ "package_id", "url", "file_name" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or its package does not exist, or the broker cannot read it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The package is not built, or it changed after its build (PACKAGE_NOT_READY, PACKAGE_STALE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/program": { "get": { "operationId": "getComplianceProgram", "summary": "Retrieve the compliance program", "description": "The brokerage's compliance program, as its compliance setup shows it: the officers, the screening and identity rules, who gets each alert, the five program documents, and the firm's facts that the borrower disclosure prints. A brokerage has one program.", "tags": [ "Compliance" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_program", "description": "The type of this record. Always `compliance_program`.", "type": "string", "enum": [ "compliance_program" ] }, "id": { "type": "string", "description": "Stable identifier for the program. A brokerage has one." }, "setup_completed_at": { "nullable": true, "description": "When the brokerage finished the compliance setup. Null until then.", "type": "string" }, "provinces": { "type": "array", "items": { "type": "string" }, "description": "The provinces that the brokerage works in, as two-letter codes." }, "designated_officer_ids": { "type": "array", "items": { "type": "string" }, "description": "The brokers who are the designated compliance officers. Resolve them with `GET /v1/users`." }, "screening_cadence_years": { "type": "object", "properties": { "low": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a low-risk client." }, "medium": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a medium-risk client." }, "high": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a high-risk client." } }, "required": [ "low", "medium", "high" ], "additionalProperties": false, "description": "How often a client is screened again, by risk rating." }, "auto_screen_on_import": { "type": "boolean", "description": "A client brought in from an import is screened at once." }, "identity_methods": { "type": "array", "items": { "type": "string" }, "description": "The ways that a client can prove their identity, for example `government_photo_id`. BrokerPlus runs only `government_photo_id` today." }, "identity_reverification_max_days": { "nullable": true, "description": "How old an identity check can be, in days, before the client proves it again. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "identity_clean_result_auto_approve": { "type": "boolean", "description": "A fully clear result from the identity provider is approved without a broker." }, "mpp_required_before_funding": { "type": "boolean", "description": "A deal cannot fund until creditor insurance was offered to the client." }, "screening_review_threshold": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The match score, from 0 to 100, at or above which a screening match is shown for review first." }, "representation_basis": { "nullable": true, "description": "Whom the brokerage acts for, as the borrower disclosure states it: the borrower, the lender, or both. Null if not given.", "type": "string", "enum": [ "borrower_only", "lender_only", "both_no_preference" ] }, "lenders_acted_for_previous_year": { "nullable": true, "description": "How many lenders the brokerage acted for in the previous fiscal year. Null if not given.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "was_lender_previous_year": { "nullable": true, "description": "The brokerage was itself a lender in the previous fiscal year. Null if not given.", "type": "boolean" }, "acts_as_lender_on_files": { "nullable": true, "description": "The brokerage lends its own funds on a file. Null if not given.", "type": "boolean" }, "effectiveness_review_due_at": { "nullable": true, "description": "When the next review of the program is due. Null if not set.", "type": "string" }, "alert_routing": { "type": "object", "properties": { "urgent": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for an `urgent` alert." }, "normal": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for a `normal` alert." }, "low": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for a `low` alert." } }, "required": [ "urgent", "normal", "low" ], "additionalProperties": false, "description": "Who gets an email for a monitoring alert, by severity." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "program", "policies", "risk_methodology", "training_curriculum", "biennial_review" ], "description": "Which program document it is." }, "uploaded": { "type": "boolean", "description": "The brokerage uploaded a PDF of it." }, "external_url": { "nullable": true, "description": "The link to it, when the brokerage keeps it elsewhere.", "type": "string" } }, "required": [ "type", "uploaded", "external_url" ], "additionalProperties": false }, "description": "The five documents that a compliance program must have, and whether each is there." }, "created_at": { "type": "string", "description": "When the program was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "setup_completed_at", "provinces", "designated_officer_ids", "screening_cadence_years", "auto_screen_on_import", "identity_methods", "identity_reverification_max_days", "identity_clean_result_auto_approve", "mpp_required_before_funding", "screening_review_threshold", "representation_basis", "lenders_acted_for_previous_year", "was_lender_previous_year", "acts_as_lender_on_files", "effectiveness_review_due_at", "alert_routing", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateComplianceProgram", "summary": "Update the firm's disclosure facts", "description": "Changes the facts about the brokerage that the borrower disclosure prints: whom the brokerage acts for, how many lenders it acted for last year, and whether it lends. Null clears a fact, and the disclosure then prints it unanswered. Only a compliance administrator can change them. The rest of the program changes only in BrokerPlus.", "tags": [ "Compliance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "representation_basis": { "description": "Whom the brokerage acts for: the borrower, the lender, or both. Null clears it.", "nullable": true, "type": "string", "enum": [ "borrower_only", "lender_only", "both_no_preference" ] }, "lenders_acted_for_previous_year": { "description": "How many lenders the brokerage acted for in the previous fiscal year. Null clears it.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 10000 }, "was_lender_previous_year": { "description": "The brokerage was itself a lender in the previous fiscal year. Null clears it.", "nullable": true, "type": "boolean" }, "acts_as_lender_on_files": { "description": "The brokerage lends its own funds on a file. Null clears it.", "nullable": true, "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_program", "description": "The type of this record. Always `compliance_program`.", "type": "string", "enum": [ "compliance_program" ] }, "id": { "type": "string", "description": "Stable identifier for the program. A brokerage has one." }, "setup_completed_at": { "nullable": true, "description": "When the brokerage finished the compliance setup. Null until then.", "type": "string" }, "provinces": { "type": "array", "items": { "type": "string" }, "description": "The provinces that the brokerage works in, as two-letter codes." }, "designated_officer_ids": { "type": "array", "items": { "type": "string" }, "description": "The brokers who are the designated compliance officers. Resolve them with `GET /v1/users`." }, "screening_cadence_years": { "type": "object", "properties": { "low": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a low-risk client." }, "medium": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a medium-risk client." }, "high": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Years between screenings for a high-risk client." } }, "required": [ "low", "medium", "high" ], "additionalProperties": false, "description": "How often a client is screened again, by risk rating." }, "auto_screen_on_import": { "type": "boolean", "description": "A client brought in from an import is screened at once." }, "identity_methods": { "type": "array", "items": { "type": "string" }, "description": "The ways that a client can prove their identity, for example `government_photo_id`. BrokerPlus runs only `government_photo_id` today." }, "identity_reverification_max_days": { "nullable": true, "description": "How old an identity check can be, in days, before the client proves it again. Null for no limit.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "identity_clean_result_auto_approve": { "type": "boolean", "description": "A fully clear result from the identity provider is approved without a broker." }, "mpp_required_before_funding": { "type": "boolean", "description": "A deal cannot fund until creditor insurance was offered to the client." }, "screening_review_threshold": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The match score, from 0 to 100, at or above which a screening match is shown for review first." }, "representation_basis": { "nullable": true, "description": "Whom the brokerage acts for, as the borrower disclosure states it: the borrower, the lender, or both. Null if not given.", "type": "string", "enum": [ "borrower_only", "lender_only", "both_no_preference" ] }, "lenders_acted_for_previous_year": { "nullable": true, "description": "How many lenders the brokerage acted for in the previous fiscal year. Null if not given.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "was_lender_previous_year": { "nullable": true, "description": "The brokerage was itself a lender in the previous fiscal year. Null if not given.", "type": "boolean" }, "acts_as_lender_on_files": { "nullable": true, "description": "The brokerage lends its own funds on a file. Null if not given.", "type": "boolean" }, "effectiveness_review_due_at": { "nullable": true, "description": "When the next review of the program is due. Null if not set.", "type": "string" }, "alert_routing": { "type": "object", "properties": { "urgent": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for an `urgent` alert." }, "normal": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for a `normal` alert." }, "low": { "type": "object", "properties": { "officer": { "type": "boolean", "description": "The designated compliance officers get the alert by email." }, "senior_management": { "type": "boolean", "description": "The brokerage's compliance reviewers get the alert by email." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Other brokers who get the alert by email." } }, "required": [ "officer", "senior_management", "user_ids" ], "additionalProperties": false, "description": "Who gets an email for a `low` alert." } }, "required": [ "urgent", "normal", "low" ], "additionalProperties": false, "description": "Who gets an email for a monitoring alert, by severity." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "program", "policies", "risk_methodology", "training_curriculum", "biennial_review" ], "description": "Which program document it is." }, "uploaded": { "type": "boolean", "description": "The brokerage uploaded a PDF of it." }, "external_url": { "nullable": true, "description": "The link to it, when the brokerage keeps it elsewhere.", "type": "string" } }, "required": [ "type", "uploaded", "external_url" ], "additionalProperties": false }, "description": "The five documents that a compliance program must have, and whether each is there." }, "created_at": { "type": "string", "description": "When the program was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "setup_completed_at", "provinces", "designated_officer_ids", "screening_cadence_years", "auto_screen_on_import", "identity_methods", "identity_reverification_max_days", "identity_clean_result_auto_approve", "mpp_required_before_funding", "screening_review_threshold", "representation_basis", "lenders_acted_for_previous_year", "was_lender_previous_year", "acts_as_lender_on_files", "effectiveness_review_due_at", "alert_routing", "documents", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The body is empty, or a value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker is not a compliance administrator (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/trainings": { "get": { "operationId": "listComplianceTrainings", "summary": "List compliance training records", "description": "The compliance training that each broker in the brokerage finished, newest first. Only a brokerage administrator can read them.", "tags": [ "Compliance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the records of this broker." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "compliance_training", "description": "The type of this record. Always `compliance_training`.", "type": "string", "enum": [ "compliance_training" ] }, "id": { "type": "string", "description": "Stable identifier for the record." }, "user_id": { "type": "string", "description": "The broker who did the training." }, "user_name": { "nullable": true, "description": "The broker's name, for display.", "type": "string" }, "training_type": { "type": "string", "description": "The training, for example `aml_initial` or `aml_annual`." }, "cycle": { "type": "string", "description": "The period that the training counts for, for example `2026`." }, "completed_at": { "type": "string", "description": "When the broker finished it." }, "has_certificate": { "type": "boolean", "description": "A certificate is on file." }, "created_at": { "type": "string", "description": "When the record was made." } }, "required": [ "object", "id", "user_id", "user_name", "training_type", "cycle", "completed_at", "has_certificate", "created_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The broker is not a brokerage administrator (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/retention-policies": { "get": { "operationId": "listRetentionPolicies", "summary": "List record retention policies", "description": "How many years BrokerPlus keeps each kind of record, by province.", "tags": [ "Compliance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "retention_policy", "description": "The type of this record. Always `retention_policy`.", "type": "string", "enum": [ "retention_policy" ] }, "id": { "type": "string", "description": "Stable identifier for the policy." }, "record_class": { "type": "string", "description": "The kind of record: `deal_file`, `consent`, `identity_verification`, `screening`, `disclosure` or `suitability`." }, "jurisdiction": { "type": "string", "description": "The two-letter province code, or `federal`." }, "retain_years": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many years BrokerPlus keeps the record." }, "basis": { "nullable": true, "description": "The rule that sets the period. Null if not given.", "type": "string" }, "created_at": { "type": "string", "description": "When the policy was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "record_class", "jurisdiction", "retain_years", "basis", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/verifier-policy": { "get": { "operationId": "getVerifierPolicy", "summary": "Retrieve the document check policy", "description": "How the brokerage runs the instant check of a client's documents: whether it is on, who can run it, and how strict it is.", "tags": [ "Compliance" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "verifier_policy", "description": "The type of this record. Always `verifier_policy`.", "type": "string", "enum": [ "verifier_policy" ] }, "id": { "type": "string", "description": "Stable identifier for the policy. A brokerage has one." }, "enabled": { "type": "boolean", "description": "The instant document check is on." }, "access": { "type": "string", "enum": [ "all_brokers", "admins_only" ], "description": "Who can run the check: every broker (`all_brokers`), or the brokerage's administrators." }, "strictness": { "type": "string", "enum": [ "standard", "strict" ], "description": "`strict` keeps an old document flagged. `standard` lets the check clear it." }, "permitted_doc_types": { "type": "array", "items": { "type": "string" }, "description": "The document types that the check accepts. Empty for every type." }, "created_at": { "type": "string", "description": "When the policy was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "enabled", "access", "strictness", "permitted_doc_types", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/monitoring-alerts": { "get": { "operationId": "listMonitoringAlerts", "summary": "List monitoring alerts", "description": "The alerts that screening raised about clients, the most recent first. A compliance reviewer sees every alert in the brokerage. A broker sees the alerts on their own clients. An alert is dismissed or resolved only in BrokerPlus.", "tags": [ "Compliance" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "dismissed", "resolved" ] }, "description": "Only the alerts with this status." }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "urgent", "normal", "low" ] }, "description": "Only the alerts with this severity." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the alerts about this client." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "monitoring_alert", "description": "The type of this record. Always `monitoring_alert`.", "type": "string", "enum": [ "monitoring_alert" ] }, "id": { "type": "string", "description": "Stable identifier for the alert." }, "contact_id": { "type": "string", "description": "The client that the alert is about." }, "contact_name": { "nullable": true, "description": "The client's name, for display.", "type": "string" }, "alert_type": { "type": "string", "description": "What the screening found, for example `match_surfaced`." }, "description": { "type": "string", "description": "What the alert means and what to do, in words." }, "severity": { "type": "string", "enum": [ "urgent", "normal", "low" ], "description": "How soon the alert needs a look." }, "status": { "type": "string", "description": "`open` until a broker dismisses or resolves it." }, "dismissed_at": { "nullable": true, "description": "When a broker dismissed it. Null if not dismissed.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who dismissed it. Null if not dismissed.", "type": "string" }, "dismissal_reason": { "nullable": true, "description": "Why it was dismissed. Null if not given.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was resolved. Null if not resolved.", "type": "string" }, "occurrence_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the same finding came in within 7 days." }, "last_occurred_at": { "type": "string", "description": "When the finding last came in." }, "created_at": { "type": "string", "description": "When the alert was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "contact_name", "alert_type", "description", "severity", "status", "dismissed_at", "dismissed_by_user_id", "dismissal_reason", "resolved_at", "occurrence_count", "last_occurred_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "A query value is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/compliance/monitoring-alerts/{id}": { "get": { "operationId": "getMonitoringAlert", "summary": "Retrieve a monitoring alert", "description": "One monitoring alert.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "monitoring_alert", "description": "The type of this record. Always `monitoring_alert`.", "type": "string", "enum": [ "monitoring_alert" ] }, "id": { "type": "string", "description": "Stable identifier for the alert." }, "contact_id": { "type": "string", "description": "The client that the alert is about." }, "contact_name": { "nullable": true, "description": "The client's name, for display.", "type": "string" }, "alert_type": { "type": "string", "description": "What the screening found, for example `match_surfaced`." }, "description": { "type": "string", "description": "What the alert means and what to do, in words." }, "severity": { "type": "string", "enum": [ "urgent", "normal", "low" ], "description": "How soon the alert needs a look." }, "status": { "type": "string", "description": "`open` until a broker dismisses or resolves it." }, "dismissed_at": { "nullable": true, "description": "When a broker dismissed it. Null if not dismissed.", "type": "string" }, "dismissed_by_user_id": { "nullable": true, "description": "The broker who dismissed it. Null if not dismissed.", "type": "string" }, "dismissal_reason": { "nullable": true, "description": "Why it was dismissed. Null if not given.", "type": "string" }, "resolved_at": { "nullable": true, "description": "When it was resolved. Null if not resolved.", "type": "string" }, "occurrence_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many times the same finding came in within 7 days." }, "last_occurred_at": { "type": "string", "description": "When the finding last came in." }, "created_at": { "type": "string", "description": "When the alert was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "contact_name", "alert_type", "description", "severity", "status", "dismissed_at", "dismissed_by_user_id", "dismissal_reason", "resolved_at", "occurrence_count", "last_occurred_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No alert the broker can read has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/signing-policies": { "get": { "operationId": "listSigningPolicies", "summary": "List e-signing rules", "description": "Which connected e-signing provider a team's documents go out through: the team's default, and an exception for a lender that does not accept it. Lists the rules of the broker's teams, all on one page.", "tags": [ "Compliance" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "signing_policy", "description": "The type of this record. Always `signing_policy`.", "type": "string", "enum": [ "signing_policy" ] }, "id": { "type": "string", "description": "Stable identifier for the rule." }, "team_id": { "nullable": true, "description": "The team whose documents the rule routes. Null for a rule of the whole brokerage.", "type": "string" }, "scope": { "type": "string", "enum": [ "default", "lender" ], "description": "`default` is the team's provider for every document. `lender` is an exception for one lender." }, "lender_slug": { "nullable": true, "description": "The lender of a `lender` rule. Null for the default.", "type": "string" }, "provider": { "type": "string", "description": "The e-signing provider that the documents go out through, for example `docusign`." }, "provider_name": { "type": "string", "description": "The provider's name, for display." }, "connection_status": { "type": "string", "description": "The state of the team's connection to the provider, for example `active`." }, "note": { "nullable": true, "description": "Why the rule is there, for the next broker. Null if not given.", "type": "string" }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "team_id", "scope", "lender_slug", "provider", "provider_name", "connection_status", "note", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "saveSigningPolicy", "summary": "Set an e-signing rule", "description": "Sets the team's default provider, or the provider for one lender. The team must have connected the provider in BrokerPlus. A team has one default and one rule per lender, so a second call for the same rule changes it: that answers `200`, and a new rule `201`.", "tags": [ "Compliance" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "default", "lender" ], "description": "`default` for the team's provider, `lender` for one lender." }, "lender_slug": { "description": "The lender. Needed for a `lender` rule.", "nullable": true, "type": "string", "minLength": 1, "maxLength": 120 }, "provider": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The e-signing provider, for example `docusign`. The team must have connected it in BrokerPlus." }, "team_id": { "description": "The team whose connection the rule uses. Needed only when more than one of the broker's teams connected the provider.", "type": "string" }, "note": { "description": "Why the rule is there, for the next broker.", "nullable": true, "type": "string", "maxLength": 2000 } }, "required": [ "scope", "provider" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "signing_policy", "description": "The type of this record. Always `signing_policy`.", "type": "string", "enum": [ "signing_policy" ] }, "id": { "type": "string", "description": "Stable identifier for the rule." }, "team_id": { "nullable": true, "description": "The team whose documents the rule routes. Null for a rule of the whole brokerage.", "type": "string" }, "scope": { "type": "string", "enum": [ "default", "lender" ], "description": "`default` is the team's provider for every document. `lender` is an exception for one lender." }, "lender_slug": { "nullable": true, "description": "The lender of a `lender` rule. Null for the default.", "type": "string" }, "provider": { "type": "string", "description": "The e-signing provider that the documents go out through, for example `docusign`." }, "provider_name": { "type": "string", "description": "The provider's name, for display." }, "connection_status": { "type": "string", "description": "The state of the team's connection to the provider, for example `active`." }, "note": { "nullable": true, "description": "Why the rule is there, for the next broker. Null if not given.", "type": "string" }, "created_at": { "type": "string", "description": "When the rule was made." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "team_id", "scope", "lender_slug", "provider", "provider_name", "connection_status", "note", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A `lender` rule has no `lender_slug`, more than one of the broker's teams connected the provider and `team_id` is not sent, or the body is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "None of the broker's teams has an active connection to the provider (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/signing-policies/{id}": { "delete": { "operationId": "deleteSigningPolicy", "summary": "Delete an e-signing rule", "description": "Deletes the rule. A lender's documents then go out through the team's default, and with no default, through BrokerPlus's own signing.", "tags": [ "Compliance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No rule of the broker's teams has this id (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/kyc-records": { "get": { "operationId": "listDealKycRecords", "summary": "List a deal's know-your-client records", "description": "The know-your-client records on the deal, one for each party that has one, as the KYC editor on the deal's compliance tab shows them: the purpose of the relationship, the occupation, the source of funds, the third-party determination, and the identity and politically exposed person answers that came with an imported deal. The ID document number is masked, and the credit file number is not published. `GET /deals/{id}/compliance` tells you which parties still need a record.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "kyc_record", "description": "The type of this record. Always `kyc_record`.", "type": "string", "enum": [ "kyc_record" ] }, "id": { "type": "string", "description": "Stable identifier for the record." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "relationship_purpose": { "nullable": true, "description": "The purpose of the business relationship. Null until the broker records it.", "type": "string", "enum": [ "purchase_financing", "refinance", "renewal", "debt_consolidation", "construction", "investment_property", "reverse_mortgage", "other" ] }, "intended_nature": { "nullable": true, "description": "The intended nature of the business relationship.", "type": "string" }, "is_repeat_client": { "type": "boolean", "description": "True when the brokerage already had a business relationship with the client." }, "occupation": { "nullable": true, "description": "The occupation of a person.", "type": "string" }, "employer_or_business_name": { "nullable": true, "description": "The employer of a person, or the name of a business.", "type": "string" }, "nature_of_business": { "nullable": true, "description": "The nature of the business of an entity.", "type": "string" }, "country_of_birth": { "nullable": true, "description": "The country of birth, as the source system recorded it.", "type": "string" }, "residency_status": { "nullable": true, "description": "The residency status, as the source system recorded it.", "type": "string" }, "delivery_channel": { "nullable": true, "description": "How the client came to the broker, for example `face_to_face` or `internet`.", "type": "string", "enum": [ "face_to_face", "internet", "phone", "chat", "email", "esign", "mail", "agent_or_mandatary", "repeat_client" ] }, "source_of_funds_known": { "nullable": true, "description": "True when the source of the funds is known.", "type": "boolean" }, "source_of_funds_description": { "nullable": true, "description": "Where the funds come from.", "type": "string" }, "is_business_legal_entity": { "nullable": true, "description": "True when the client is an entity, not a person. Null when the source system did not say.", "type": "boolean" }, "id_verification_method": { "nullable": true, "description": "How the source system verified the party's identity. This and the other `id_` fields are read only: they come from the system the deal was imported from.", "type": "string", "enum": [ "credit_file", "government_photo_id", "dual_source" ] }, "id_verified_on": { "nullable": true, "description": "The date of the identity check, as `YYYY-MM-DD`.", "type": "string" }, "id_verification_complete": { "nullable": true, "description": "True when the source system marked the check complete.", "type": "boolean" }, "id_document_type": { "nullable": true, "description": "The type of ID document that was examined.", "type": "string" }, "id_document_number": { "nullable": true, "description": "The number of the ID document, masked: only the last four characters show, for example `••••5678`.", "type": "string" }, "id_document_country": { "nullable": true, "description": "The country that issued the photo ID.", "type": "string" }, "id_document_jurisdiction": { "nullable": true, "description": "The province or state that issued the photo ID.", "type": "string" }, "id_document_expires_on": { "nullable": true, "description": "When the photo ID expires, as `YYYY-MM-DD`.", "type": "string" }, "credit_file_bureau": { "nullable": true, "description": "The credit bureau of a credit file check. The credit file number is not published.", "type": "string" }, "dual_source_first_name": { "nullable": true, "description": "The first source of a dual-source check.", "type": "string" }, "dual_source_second_name": { "nullable": true, "description": "The second source of a dual-source check.", "type": "string" }, "pep_declared": { "nullable": true, "description": "The politically exposed person answer, as the source system recorded it for this deal. This and the other `pep_` fields are read only.", "type": "boolean" }, "pep_relation": { "nullable": true, "description": "Who the politically exposed person is to the party, for example `borrower` or `family_member`.", "type": "string" }, "pep_role_position": { "nullable": true, "description": "The office or position of the politically exposed person.", "type": "string" }, "pep_source_of_wealth": { "nullable": true, "description": "The source of wealth that the source system recorded.", "type": "string" }, "pep_measures_taken": { "nullable": true, "description": "The measures that the source system recorded.", "type": "string" }, "pep_determination_note": { "nullable": true, "description": "The note on the determination, as the broker typed it.", "type": "string" }, "third_party_determination": { "type": "string", "enum": [ "not_determined", "no_third_party", "third_party_identified", "unable_to_determine" ], "description": "Whether the client acts for another person. `not_determined` until the broker decides. `unable_to_determine` needs `third_party_suspicion_reasons`." }, "third_party_measures": { "nullable": true, "description": "The measures the broker took to make the determination.", "type": "string" }, "third_party_suspicion_reasons": { "nullable": true, "description": "Why a third party is still suspected, when the broker could not determine it.", "type": "string" }, "client_own_behalf_attested": { "type": "boolean", "description": "True when the client attested that they act for themselves." }, "determined_at": { "nullable": true, "description": "When the broker last made a determination other than `not_determined`. Null until then.", "type": "string" }, "determined_by_user_id": { "nullable": true, "description": "The broker who made that determination.", "type": "string" }, "third_parties": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "kyc_third_party", "description": "The type of this record. Always `kyc_third_party`.", "type": "string", "enum": [ "kyc_third_party" ] }, "id": { "type": "string", "description": "Stable identifier for the third party. A save of the list makes new ones." }, "kind": { "type": "string", "enum": [ "individual", "entity" ], "description": "`individual` for a person, `entity` for a company or a trust." }, "name": { "type": "string", "description": "The third party's name." }, "address": { "nullable": true, "description": "The third party's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The date of birth of a person, as `YYYY-MM-DD`.", "type": "string" }, "incorporation_number": { "nullable": true, "description": "The incorporation number of an entity.", "type": "string" }, "incorporation_jurisdiction": { "nullable": true, "description": "Where the entity is incorporated.", "type": "string" }, "occupation_or_business": { "nullable": true, "description": "The person's occupation, or the entity's business.", "type": "string" }, "relationship_to_client": { "nullable": true, "description": "How the third party is related to the client.", "type": "string" } }, "required": [ "object", "id", "kind", "name", "address", "date_of_birth", "incorporation_number", "incorporation_jurisdiction", "occupation_or_business", "relationship_to_client" ], "additionalProperties": false }, "description": "The third parties the broker identified, in the order they were entered." }, "recorded_by_user_id": { "nullable": true, "description": "The broker who first saved the record.", "type": "string" }, "created_at": { "type": "string", "description": "When the record was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "relationship_purpose", "intended_nature", "is_repeat_client", "occupation", "employer_or_business_name", "nature_of_business", "country_of_birth", "residency_status", "delivery_channel", "source_of_funds_known", "source_of_funds_description", "is_business_legal_entity", "id_verification_method", "id_verified_on", "id_verification_complete", "id_document_type", "id_document_number", "id_document_country", "id_document_jurisdiction", "id_document_expires_on", "credit_file_bureau", "dual_source_first_name", "dual_source_second_name", "pep_declared", "pep_relation", "pep_role_position", "pep_source_of_wealth", "pep_measures_taken", "pep_determination_note", "third_party_determination", "third_party_measures", "third_party_suspicion_reasons", "client_own_behalf_attested", "determined_at", "determined_by_user_id", "third_parties", "recorded_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/kyc-records/{contactId}": { "get": { "operationId": "getDealKycRecord", "summary": "Retrieve a party's know-your-client record", "description": "The know-your-client record of one party on the deal. `contactId` is the party's contact.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "kyc_record", "description": "The type of this record. Always `kyc_record`.", "type": "string", "enum": [ "kyc_record" ] }, "id": { "type": "string", "description": "Stable identifier for the record." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "relationship_purpose": { "nullable": true, "description": "The purpose of the business relationship. Null until the broker records it.", "type": "string", "enum": [ "purchase_financing", "refinance", "renewal", "debt_consolidation", "construction", "investment_property", "reverse_mortgage", "other" ] }, "intended_nature": { "nullable": true, "description": "The intended nature of the business relationship.", "type": "string" }, "is_repeat_client": { "type": "boolean", "description": "True when the brokerage already had a business relationship with the client." }, "occupation": { "nullable": true, "description": "The occupation of a person.", "type": "string" }, "employer_or_business_name": { "nullable": true, "description": "The employer of a person, or the name of a business.", "type": "string" }, "nature_of_business": { "nullable": true, "description": "The nature of the business of an entity.", "type": "string" }, "country_of_birth": { "nullable": true, "description": "The country of birth, as the source system recorded it.", "type": "string" }, "residency_status": { "nullable": true, "description": "The residency status, as the source system recorded it.", "type": "string" }, "delivery_channel": { "nullable": true, "description": "How the client came to the broker, for example `face_to_face` or `internet`.", "type": "string", "enum": [ "face_to_face", "internet", "phone", "chat", "email", "esign", "mail", "agent_or_mandatary", "repeat_client" ] }, "source_of_funds_known": { "nullable": true, "description": "True when the source of the funds is known.", "type": "boolean" }, "source_of_funds_description": { "nullable": true, "description": "Where the funds come from.", "type": "string" }, "is_business_legal_entity": { "nullable": true, "description": "True when the client is an entity, not a person. Null when the source system did not say.", "type": "boolean" }, "id_verification_method": { "nullable": true, "description": "How the source system verified the party's identity. This and the other `id_` fields are read only: they come from the system the deal was imported from.", "type": "string", "enum": [ "credit_file", "government_photo_id", "dual_source" ] }, "id_verified_on": { "nullable": true, "description": "The date of the identity check, as `YYYY-MM-DD`.", "type": "string" }, "id_verification_complete": { "nullable": true, "description": "True when the source system marked the check complete.", "type": "boolean" }, "id_document_type": { "nullable": true, "description": "The type of ID document that was examined.", "type": "string" }, "id_document_number": { "nullable": true, "description": "The number of the ID document, masked: only the last four characters show, for example `••••5678`.", "type": "string" }, "id_document_country": { "nullable": true, "description": "The country that issued the photo ID.", "type": "string" }, "id_document_jurisdiction": { "nullable": true, "description": "The province or state that issued the photo ID.", "type": "string" }, "id_document_expires_on": { "nullable": true, "description": "When the photo ID expires, as `YYYY-MM-DD`.", "type": "string" }, "credit_file_bureau": { "nullable": true, "description": "The credit bureau of a credit file check. The credit file number is not published.", "type": "string" }, "dual_source_first_name": { "nullable": true, "description": "The first source of a dual-source check.", "type": "string" }, "dual_source_second_name": { "nullable": true, "description": "The second source of a dual-source check.", "type": "string" }, "pep_declared": { "nullable": true, "description": "The politically exposed person answer, as the source system recorded it for this deal. This and the other `pep_` fields are read only.", "type": "boolean" }, "pep_relation": { "nullable": true, "description": "Who the politically exposed person is to the party, for example `borrower` or `family_member`.", "type": "string" }, "pep_role_position": { "nullable": true, "description": "The office or position of the politically exposed person.", "type": "string" }, "pep_source_of_wealth": { "nullable": true, "description": "The source of wealth that the source system recorded.", "type": "string" }, "pep_measures_taken": { "nullable": true, "description": "The measures that the source system recorded.", "type": "string" }, "pep_determination_note": { "nullable": true, "description": "The note on the determination, as the broker typed it.", "type": "string" }, "third_party_determination": { "type": "string", "enum": [ "not_determined", "no_third_party", "third_party_identified", "unable_to_determine" ], "description": "Whether the client acts for another person. `not_determined` until the broker decides. `unable_to_determine` needs `third_party_suspicion_reasons`." }, "third_party_measures": { "nullable": true, "description": "The measures the broker took to make the determination.", "type": "string" }, "third_party_suspicion_reasons": { "nullable": true, "description": "Why a third party is still suspected, when the broker could not determine it.", "type": "string" }, "client_own_behalf_attested": { "type": "boolean", "description": "True when the client attested that they act for themselves." }, "determined_at": { "nullable": true, "description": "When the broker last made a determination other than `not_determined`. Null until then.", "type": "string" }, "determined_by_user_id": { "nullable": true, "description": "The broker who made that determination.", "type": "string" }, "third_parties": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "kyc_third_party", "description": "The type of this record. Always `kyc_third_party`.", "type": "string", "enum": [ "kyc_third_party" ] }, "id": { "type": "string", "description": "Stable identifier for the third party. A save of the list makes new ones." }, "kind": { "type": "string", "enum": [ "individual", "entity" ], "description": "`individual` for a person, `entity` for a company or a trust." }, "name": { "type": "string", "description": "The third party's name." }, "address": { "nullable": true, "description": "The third party's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The date of birth of a person, as `YYYY-MM-DD`.", "type": "string" }, "incorporation_number": { "nullable": true, "description": "The incorporation number of an entity.", "type": "string" }, "incorporation_jurisdiction": { "nullable": true, "description": "Where the entity is incorporated.", "type": "string" }, "occupation_or_business": { "nullable": true, "description": "The person's occupation, or the entity's business.", "type": "string" }, "relationship_to_client": { "nullable": true, "description": "How the third party is related to the client.", "type": "string" } }, "required": [ "object", "id", "kind", "name", "address", "date_of_birth", "incorporation_number", "incorporation_jurisdiction", "occupation_or_business", "relationship_to_client" ], "additionalProperties": false }, "description": "The third parties the broker identified, in the order they were entered." }, "recorded_by_user_id": { "nullable": true, "description": "The broker who first saved the record.", "type": "string" }, "created_at": { "type": "string", "description": "When the record was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "relationship_purpose", "intended_nature", "is_repeat_client", "occupation", "employer_or_business_name", "nature_of_business", "country_of_birth", "residency_status", "delivery_channel", "source_of_funds_known", "source_of_funds_description", "is_business_legal_entity", "id_verification_method", "id_verified_on", "id_verification_complete", "id_document_type", "id_document_number", "id_document_country", "id_document_jurisdiction", "id_document_expires_on", "credit_file_bureau", "dual_source_first_name", "dual_source_second_name", "pep_declared", "pep_relation", "pep_role_position", "pep_source_of_wealth", "pep_measures_taken", "pep_determination_note", "third_party_determination", "third_party_measures", "third_party_suspicion_reasons", "client_own_behalf_attested", "determined_at", "determined_by_user_id", "third_parties", "recorded_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The party is not on the deal, the broker cannot change the deal, or the party has no record yet (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealKycRecord", "summary": "Save a party's know-your-client record", "description": "Saves the know-your-client record of one party on the deal, as the KYC editor does. It makes the record if the party has none. Only the fields you send change; `third_parties` replaces the whole list. The identity and politically exposed person fields from an imported deal are read only.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship_purpose": { "description": "The purpose of the relationship.", "nullable": true, "type": "string", "enum": [ "purchase_financing", "refinance", "renewal", "debt_consolidation", "construction", "investment_property", "reverse_mortgage", "other" ] }, "intended_nature": { "description": "The intended nature of the relationship.", "nullable": true, "type": "string", "maxLength": 2000 }, "is_repeat_client": { "description": "True when the brokerage already works with the client.", "type": "boolean" }, "occupation": { "description": "The occupation of a person.", "nullable": true, "type": "string", "maxLength": 200 }, "employer_or_business_name": { "description": "The employer, or the business name.", "nullable": true, "type": "string", "maxLength": 200 }, "nature_of_business": { "description": "The nature of the business of an entity.", "nullable": true, "type": "string", "maxLength": 2000 }, "delivery_channel": { "description": "How the client came to the broker.", "nullable": true, "type": "string", "enum": [ "face_to_face", "internet", "phone", "chat", "email", "esign", "mail", "agent_or_mandatary", "repeat_client" ] }, "source_of_funds_known": { "description": "True when the source of the funds is known.", "nullable": true, "type": "boolean" }, "source_of_funds_description": { "description": "Where the funds come from.", "nullable": true, "type": "string", "maxLength": 2000 }, "third_party_determination": { "description": "Whether the client acts for another person. A value other than `not_determined` sets `determined_at`.", "type": "string", "enum": [ "not_determined", "no_third_party", "third_party_identified", "unable_to_determine" ] }, "third_party_measures": { "description": "The measures taken to determine it.", "nullable": true, "type": "string", "maxLength": 2000 }, "third_party_suspicion_reasons": { "description": "Why a third party is still suspected.", "nullable": true, "type": "string", "maxLength": 2000 }, "client_own_behalf_attested": { "description": "True when the client attests they act for themselves.", "type": "boolean" }, "third_parties": { "description": "The whole list of third parties, at most 20. It replaces the list on file. Leave it out to keep the list.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "default": "individual", "description": "`individual` or `entity`.", "type": "string", "enum": [ "individual", "entity" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The third party's name." }, "address": { "description": "The address.", "nullable": true, "type": "string", "maxLength": 500 }, "date_of_birth": { "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ], "description": "An ISO 8601 date, `YYYY-MM-DD`, or a date-time with an offset." }, "incorporation_number": { "description": "The incorporation number.", "nullable": true, "type": "string", "maxLength": 100 }, "incorporation_jurisdiction": { "description": "Where it is incorporated.", "nullable": true, "type": "string", "maxLength": 100 }, "occupation_or_business": { "description": "Occupation or business.", "nullable": true, "type": "string", "maxLength": 200 }, "relationship_to_client": { "description": "The relationship to the client.", "nullable": true, "type": "string", "maxLength": 1000 } }, "required": [ "kind", "name" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "kyc_record", "description": "The type of this record. Always `kyc_record`.", "type": "string", "enum": [ "kyc_record" ] }, "id": { "type": "string", "description": "Stable identifier for the record." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "relationship_purpose": { "nullable": true, "description": "The purpose of the business relationship. Null until the broker records it.", "type": "string", "enum": [ "purchase_financing", "refinance", "renewal", "debt_consolidation", "construction", "investment_property", "reverse_mortgage", "other" ] }, "intended_nature": { "nullable": true, "description": "The intended nature of the business relationship.", "type": "string" }, "is_repeat_client": { "type": "boolean", "description": "True when the brokerage already had a business relationship with the client." }, "occupation": { "nullable": true, "description": "The occupation of a person.", "type": "string" }, "employer_or_business_name": { "nullable": true, "description": "The employer of a person, or the name of a business.", "type": "string" }, "nature_of_business": { "nullable": true, "description": "The nature of the business of an entity.", "type": "string" }, "country_of_birth": { "nullable": true, "description": "The country of birth, as the source system recorded it.", "type": "string" }, "residency_status": { "nullable": true, "description": "The residency status, as the source system recorded it.", "type": "string" }, "delivery_channel": { "nullable": true, "description": "How the client came to the broker, for example `face_to_face` or `internet`.", "type": "string", "enum": [ "face_to_face", "internet", "phone", "chat", "email", "esign", "mail", "agent_or_mandatary", "repeat_client" ] }, "source_of_funds_known": { "nullable": true, "description": "True when the source of the funds is known.", "type": "boolean" }, "source_of_funds_description": { "nullable": true, "description": "Where the funds come from.", "type": "string" }, "is_business_legal_entity": { "nullable": true, "description": "True when the client is an entity, not a person. Null when the source system did not say.", "type": "boolean" }, "id_verification_method": { "nullable": true, "description": "How the source system verified the party's identity. This and the other `id_` fields are read only: they come from the system the deal was imported from.", "type": "string", "enum": [ "credit_file", "government_photo_id", "dual_source" ] }, "id_verified_on": { "nullable": true, "description": "The date of the identity check, as `YYYY-MM-DD`.", "type": "string" }, "id_verification_complete": { "nullable": true, "description": "True when the source system marked the check complete.", "type": "boolean" }, "id_document_type": { "nullable": true, "description": "The type of ID document that was examined.", "type": "string" }, "id_document_number": { "nullable": true, "description": "The number of the ID document, masked: only the last four characters show, for example `••••5678`.", "type": "string" }, "id_document_country": { "nullable": true, "description": "The country that issued the photo ID.", "type": "string" }, "id_document_jurisdiction": { "nullable": true, "description": "The province or state that issued the photo ID.", "type": "string" }, "id_document_expires_on": { "nullable": true, "description": "When the photo ID expires, as `YYYY-MM-DD`.", "type": "string" }, "credit_file_bureau": { "nullable": true, "description": "The credit bureau of a credit file check. The credit file number is not published.", "type": "string" }, "dual_source_first_name": { "nullable": true, "description": "The first source of a dual-source check.", "type": "string" }, "dual_source_second_name": { "nullable": true, "description": "The second source of a dual-source check.", "type": "string" }, "pep_declared": { "nullable": true, "description": "The politically exposed person answer, as the source system recorded it for this deal. This and the other `pep_` fields are read only.", "type": "boolean" }, "pep_relation": { "nullable": true, "description": "Who the politically exposed person is to the party, for example `borrower` or `family_member`.", "type": "string" }, "pep_role_position": { "nullable": true, "description": "The office or position of the politically exposed person.", "type": "string" }, "pep_source_of_wealth": { "nullable": true, "description": "The source of wealth that the source system recorded.", "type": "string" }, "pep_measures_taken": { "nullable": true, "description": "The measures that the source system recorded.", "type": "string" }, "pep_determination_note": { "nullable": true, "description": "The note on the determination, as the broker typed it.", "type": "string" }, "third_party_determination": { "type": "string", "enum": [ "not_determined", "no_third_party", "third_party_identified", "unable_to_determine" ], "description": "Whether the client acts for another person. `not_determined` until the broker decides. `unable_to_determine` needs `third_party_suspicion_reasons`." }, "third_party_measures": { "nullable": true, "description": "The measures the broker took to make the determination.", "type": "string" }, "third_party_suspicion_reasons": { "nullable": true, "description": "Why a third party is still suspected, when the broker could not determine it.", "type": "string" }, "client_own_behalf_attested": { "type": "boolean", "description": "True when the client attested that they act for themselves." }, "determined_at": { "nullable": true, "description": "When the broker last made a determination other than `not_determined`. Null until then.", "type": "string" }, "determined_by_user_id": { "nullable": true, "description": "The broker who made that determination.", "type": "string" }, "third_parties": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "kyc_third_party", "description": "The type of this record. Always `kyc_third_party`.", "type": "string", "enum": [ "kyc_third_party" ] }, "id": { "type": "string", "description": "Stable identifier for the third party. A save of the list makes new ones." }, "kind": { "type": "string", "enum": [ "individual", "entity" ], "description": "`individual` for a person, `entity` for a company or a trust." }, "name": { "type": "string", "description": "The third party's name." }, "address": { "nullable": true, "description": "The third party's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The date of birth of a person, as `YYYY-MM-DD`.", "type": "string" }, "incorporation_number": { "nullable": true, "description": "The incorporation number of an entity.", "type": "string" }, "incorporation_jurisdiction": { "nullable": true, "description": "Where the entity is incorporated.", "type": "string" }, "occupation_or_business": { "nullable": true, "description": "The person's occupation, or the entity's business.", "type": "string" }, "relationship_to_client": { "nullable": true, "description": "How the third party is related to the client.", "type": "string" } }, "required": [ "object", "id", "kind", "name", "address", "date_of_birth", "incorporation_number", "incorporation_jurisdiction", "occupation_or_business", "relationship_to_client" ], "additionalProperties": false }, "description": "The third parties the broker identified, in the order they were entered." }, "recorded_by_user_id": { "nullable": true, "description": "The broker who first saved the record.", "type": "string" }, "created_at": { "type": "string", "description": "When the record was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "relationship_purpose", "intended_nature", "is_repeat_client", "occupation", "employer_or_business_name", "nature_of_business", "country_of_birth", "residency_status", "delivery_channel", "source_of_funds_known", "source_of_funds_description", "is_business_legal_entity", "id_verification_method", "id_verified_on", "id_verification_complete", "id_document_type", "id_document_number", "id_document_country", "id_document_jurisdiction", "id_document_expires_on", "credit_file_bureau", "dual_source_first_name", "dual_source_second_name", "pep_declared", "pep_relation", "pep_role_position", "pep_source_of_wealth", "pep_measures_taken", "pep_determination_note", "third_party_determination", "third_party_measures", "third_party_suspicion_reasons", "client_own_behalf_attested", "determined_at", "determined_by_user_id", "third_parties", "recorded_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The party is not on the deal, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/entity-verifications": { "get": { "operationId": "listDealEntityVerifications", "summary": "List a deal's entity verifications", "description": "The entity verifications on the deal, one for each company party that has one: whether the broker confirmed that the entity exists, who owns and controls it, and who can sign for it.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "entity_verification", "description": "The type of this record. Always `entity_verification`.", "type": "string", "enum": [ "entity_verification" ] }, "id": { "type": "string", "description": "Stable identifier for the verification." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "unable_to_confirm" ], "description": "`pending` until the broker decides. `confirmed`: the broker confirmed that the entity exists and who owns and controls it. `unable_to_confirm`: the broker recorded why, and treats the entity as high risk." }, "registry_source": { "nullable": true, "description": "The registry or source the broker searched.", "type": "string" }, "record_type": { "nullable": true, "description": "The type of record that confirms the entity.", "type": "string", "enum": [ "corporate_registry_search", "certificate_of_incorporation", "articles_of_incorporation", "annual_return", "partnership_agreement", "trust_deed", "other" ] }, "registration_number": { "nullable": true, "description": "The entity's registration number.", "type": "string" }, "jurisdiction": { "nullable": true, "description": "Where the entity is registered.", "type": "string" }, "searched_at": { "nullable": true, "description": "When the broker searched the registry.", "type": "string" }, "confirmation_measures": { "nullable": true, "description": "The measures the broker took to confirm the ownership and control information.", "type": "string" }, "unable_to_confirm_reason": { "nullable": true, "description": "Why the information could not be confirmed.", "type": "string" }, "senior_managing_officer_name": { "nullable": true, "description": "The senior managing officer, when it could not be confirmed.", "type": "string" }, "senior_managing_officer_title": { "nullable": true, "description": "That officer's title.", "type": "string" }, "treated_as_high_risk": { "type": "boolean", "description": "True when the broker treats the entity as high risk." }, "no_owner_at_or_above_threshold": { "type": "boolean", "description": "True when no person owns 25 percent or more of the entity. An empty `controllers` list does not say this." }, "authority_to_bind_confirmed": { "type": "boolean", "description": "True when the broker confirmed who can sign for the entity." }, "authority_to_bind_basis": { "nullable": true, "description": "How the broker confirmed it.", "type": "string" }, "controllers": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "entity_controller", "description": "The type of this record. Always `entity_controller`.", "type": "string", "enum": [ "entity_controller" ] }, "id": { "type": "string", "description": "Stable identifier for the person. A save of the list makes new ones." }, "role": { "type": "string", "enum": [ "director", "beneficial_owner", "trustee", "settlor", "known_beneficiary", "signing_officer", "senior_managing_officer" ], "description": "How the person is related to the entity, for example `director` or `beneficial_owner`." }, "name": { "type": "string", "description": "The person's name." }, "title": { "nullable": true, "description": "The person's title at the entity.", "type": "string" }, "address": { "nullable": true, "description": "The person's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The person's date of birth, as `YYYY-MM-DD`.", "type": "string" }, "ownership_percent": { "nullable": true, "description": "The share of the entity the person owns, in percent.", "type": "number" }, "ownership_is_indirect": { "type": "boolean", "description": "True when the person owns the share through other companies." }, "control_chain": { "nullable": true, "description": "The companies an indirect share goes through.", "type": "string" }, "confirmation_source": { "nullable": true, "description": "How the broker confirmed this information.", "type": "string" }, "can_bind_entity": { "type": "boolean", "description": "True when the person can sign for the entity." } }, "required": [ "object", "id", "role", "name", "title", "address", "date_of_birth", "ownership_percent", "ownership_is_indirect", "control_chain", "confirmation_source", "can_bind_entity" ], "additionalProperties": false }, "description": "The directors, owners of 25 percent or more, trust parties and signing officers, in order." }, "verified_by_user_id": { "nullable": true, "description": "The broker who last saved the verification.", "type": "string" }, "created_at": { "type": "string", "description": "When the verification was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "status", "registry_source", "record_type", "registration_number", "jurisdiction", "searched_at", "confirmation_measures", "unable_to_confirm_reason", "senior_managing_officer_name", "senior_managing_officer_title", "treated_as_high_risk", "no_owner_at_or_above_threshold", "authority_to_bind_confirmed", "authority_to_bind_basis", "controllers", "verified_by_user_id", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/entity-verifications/{contactId}": { "get": { "operationId": "getDealEntityVerification", "summary": "Retrieve a party's entity verification", "description": "The entity verification of one company party on the deal. `contactId` is the party's contact.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "entity_verification", "description": "The type of this record. Always `entity_verification`.", "type": "string", "enum": [ "entity_verification" ] }, "id": { "type": "string", "description": "Stable identifier for the verification." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "unable_to_confirm" ], "description": "`pending` until the broker decides. `confirmed`: the broker confirmed that the entity exists and who owns and controls it. `unable_to_confirm`: the broker recorded why, and treats the entity as high risk." }, "registry_source": { "nullable": true, "description": "The registry or source the broker searched.", "type": "string" }, "record_type": { "nullable": true, "description": "The type of record that confirms the entity.", "type": "string", "enum": [ "corporate_registry_search", "certificate_of_incorporation", "articles_of_incorporation", "annual_return", "partnership_agreement", "trust_deed", "other" ] }, "registration_number": { "nullable": true, "description": "The entity's registration number.", "type": "string" }, "jurisdiction": { "nullable": true, "description": "Where the entity is registered.", "type": "string" }, "searched_at": { "nullable": true, "description": "When the broker searched the registry.", "type": "string" }, "confirmation_measures": { "nullable": true, "description": "The measures the broker took to confirm the ownership and control information.", "type": "string" }, "unable_to_confirm_reason": { "nullable": true, "description": "Why the information could not be confirmed.", "type": "string" }, "senior_managing_officer_name": { "nullable": true, "description": "The senior managing officer, when it could not be confirmed.", "type": "string" }, "senior_managing_officer_title": { "nullable": true, "description": "That officer's title.", "type": "string" }, "treated_as_high_risk": { "type": "boolean", "description": "True when the broker treats the entity as high risk." }, "no_owner_at_or_above_threshold": { "type": "boolean", "description": "True when no person owns 25 percent or more of the entity. An empty `controllers` list does not say this." }, "authority_to_bind_confirmed": { "type": "boolean", "description": "True when the broker confirmed who can sign for the entity." }, "authority_to_bind_basis": { "nullable": true, "description": "How the broker confirmed it.", "type": "string" }, "controllers": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "entity_controller", "description": "The type of this record. Always `entity_controller`.", "type": "string", "enum": [ "entity_controller" ] }, "id": { "type": "string", "description": "Stable identifier for the person. A save of the list makes new ones." }, "role": { "type": "string", "enum": [ "director", "beneficial_owner", "trustee", "settlor", "known_beneficiary", "signing_officer", "senior_managing_officer" ], "description": "How the person is related to the entity, for example `director` or `beneficial_owner`." }, "name": { "type": "string", "description": "The person's name." }, "title": { "nullable": true, "description": "The person's title at the entity.", "type": "string" }, "address": { "nullable": true, "description": "The person's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The person's date of birth, as `YYYY-MM-DD`.", "type": "string" }, "ownership_percent": { "nullable": true, "description": "The share of the entity the person owns, in percent.", "type": "number" }, "ownership_is_indirect": { "type": "boolean", "description": "True when the person owns the share through other companies." }, "control_chain": { "nullable": true, "description": "The companies an indirect share goes through.", "type": "string" }, "confirmation_source": { "nullable": true, "description": "How the broker confirmed this information.", "type": "string" }, "can_bind_entity": { "type": "boolean", "description": "True when the person can sign for the entity." } }, "required": [ "object", "id", "role", "name", "title", "address", "date_of_birth", "ownership_percent", "ownership_is_indirect", "control_chain", "confirmation_source", "can_bind_entity" ], "additionalProperties": false }, "description": "The directors, owners of 25 percent or more, trust parties and signing officers, in order." }, "verified_by_user_id": { "nullable": true, "description": "The broker who last saved the verification.", "type": "string" }, "created_at": { "type": "string", "description": "When the verification was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "status", "registry_source", "record_type", "registration_number", "jurisdiction", "searched_at", "confirmation_measures", "unable_to_confirm_reason", "senior_managing_officer_name", "senior_managing_officer_title", "treated_as_high_risk", "no_owner_at_or_above_threshold", "authority_to_bind_confirmed", "authority_to_bind_basis", "controllers", "verified_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The party is not on the deal, the broker cannot change the deal, or the party has no verification yet (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealEntityVerification", "summary": "Save a party's entity verification", "description": "Saves the entity verification of one company party on the deal, as the KYC editor does. It makes the verification if the party has none. Only the fields you send change; `controllers` replaces the whole list. The documents the broker attached in BrokerPlus are not changed.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "The broker's conclusion.", "type": "string", "enum": [ "pending", "confirmed", "unable_to_confirm" ] }, "registry_source": { "description": "The registry or source searched.", "nullable": true, "type": "string", "maxLength": 200 }, "record_type": { "description": "The type of record.", "nullable": true, "type": "string", "enum": [ "corporate_registry_search", "certificate_of_incorporation", "articles_of_incorporation", "annual_return", "partnership_agreement", "trust_deed", "other" ] }, "registration_number": { "description": "The registration number.", "nullable": true, "type": "string", "maxLength": 100 }, "jurisdiction": { "description": "Where the entity is registered.", "nullable": true, "type": "string", "maxLength": 100 }, "searched_at": { "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ], "description": "An ISO 8601 date, `YYYY-MM-DD`, or a date-time with an offset." }, "confirmation_measures": { "description": "The measures taken to confirm.", "nullable": true, "type": "string", "maxLength": 2000 }, "unable_to_confirm_reason": { "description": "Why it could not be confirmed.", "nullable": true, "type": "string", "maxLength": 2000 }, "senior_managing_officer_name": { "description": "The senior managing officer.", "nullable": true, "type": "string", "maxLength": 200 }, "senior_managing_officer_title": { "description": "That officer's title.", "nullable": true, "type": "string", "maxLength": 200 }, "treated_as_high_risk": { "description": "True to treat the entity as high risk.", "type": "boolean" }, "no_owner_at_or_above_threshold": { "description": "True when nobody owns 25 percent or more.", "type": "boolean" }, "authority_to_bind_confirmed": { "description": "True when the authority to sign is confirmed.", "type": "boolean" }, "authority_to_bind_basis": { "description": "How it was confirmed.", "nullable": true, "type": "string", "maxLength": 2000 }, "controllers": { "description": "The whole list of people, at most 50. It replaces the list on file. Leave it out to keep the list.", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "beneficial_owner", "trustee", "settlor", "known_beneficiary", "signing_officer", "senior_managing_officer" ], "description": "How the person is related to the entity." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The person's name." }, "title": { "description": "The person's title.", "nullable": true, "type": "string", "maxLength": 200 }, "address": { "description": "The person's address.", "nullable": true, "type": "string", "maxLength": 500 }, "date_of_birth": { "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ], "description": "An ISO 8601 date, `YYYY-MM-DD`, or a date-time with an offset." }, "ownership_percent": { "description": "The share owned, in percent.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "ownership_is_indirect": { "description": "True when the share is owned through other companies.", "type": "boolean" }, "control_chain": { "description": "The companies it goes through.", "nullable": true, "type": "string", "maxLength": 2000 }, "confirmation_source": { "description": "How it was confirmed.", "nullable": true, "type": "string", "maxLength": 2000 }, "can_bind_entity": { "description": "True when the person can sign for the entity.", "type": "boolean" } }, "required": [ "role", "name" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "entity_verification", "description": "The type of this record. Always `entity_verification`.", "type": "string", "enum": [ "entity_verification" ] }, "id": { "type": "string", "description": "Stable identifier for the verification." }, "deal_id": { "type": "string", "description": "The deal." }, "contact_id": { "type": "string", "description": "The party on the deal that the record is about. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The party's name, for display." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "unable_to_confirm" ], "description": "`pending` until the broker decides. `confirmed`: the broker confirmed that the entity exists and who owns and controls it. `unable_to_confirm`: the broker recorded why, and treats the entity as high risk." }, "registry_source": { "nullable": true, "description": "The registry or source the broker searched.", "type": "string" }, "record_type": { "nullable": true, "description": "The type of record that confirms the entity.", "type": "string", "enum": [ "corporate_registry_search", "certificate_of_incorporation", "articles_of_incorporation", "annual_return", "partnership_agreement", "trust_deed", "other" ] }, "registration_number": { "nullable": true, "description": "The entity's registration number.", "type": "string" }, "jurisdiction": { "nullable": true, "description": "Where the entity is registered.", "type": "string" }, "searched_at": { "nullable": true, "description": "When the broker searched the registry.", "type": "string" }, "confirmation_measures": { "nullable": true, "description": "The measures the broker took to confirm the ownership and control information.", "type": "string" }, "unable_to_confirm_reason": { "nullable": true, "description": "Why the information could not be confirmed.", "type": "string" }, "senior_managing_officer_name": { "nullable": true, "description": "The senior managing officer, when it could not be confirmed.", "type": "string" }, "senior_managing_officer_title": { "nullable": true, "description": "That officer's title.", "type": "string" }, "treated_as_high_risk": { "type": "boolean", "description": "True when the broker treats the entity as high risk." }, "no_owner_at_or_above_threshold": { "type": "boolean", "description": "True when no person owns 25 percent or more of the entity. An empty `controllers` list does not say this." }, "authority_to_bind_confirmed": { "type": "boolean", "description": "True when the broker confirmed who can sign for the entity." }, "authority_to_bind_basis": { "nullable": true, "description": "How the broker confirmed it.", "type": "string" }, "controllers": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "entity_controller", "description": "The type of this record. Always `entity_controller`.", "type": "string", "enum": [ "entity_controller" ] }, "id": { "type": "string", "description": "Stable identifier for the person. A save of the list makes new ones." }, "role": { "type": "string", "enum": [ "director", "beneficial_owner", "trustee", "settlor", "known_beneficiary", "signing_officer", "senior_managing_officer" ], "description": "How the person is related to the entity, for example `director` or `beneficial_owner`." }, "name": { "type": "string", "description": "The person's name." }, "title": { "nullable": true, "description": "The person's title at the entity.", "type": "string" }, "address": { "nullable": true, "description": "The person's address.", "type": "string" }, "date_of_birth": { "nullable": true, "description": "The person's date of birth, as `YYYY-MM-DD`.", "type": "string" }, "ownership_percent": { "nullable": true, "description": "The share of the entity the person owns, in percent.", "type": "number" }, "ownership_is_indirect": { "type": "boolean", "description": "True when the person owns the share through other companies." }, "control_chain": { "nullable": true, "description": "The companies an indirect share goes through.", "type": "string" }, "confirmation_source": { "nullable": true, "description": "How the broker confirmed this information.", "type": "string" }, "can_bind_entity": { "type": "boolean", "description": "True when the person can sign for the entity." } }, "required": [ "object", "id", "role", "name", "title", "address", "date_of_birth", "ownership_percent", "ownership_is_indirect", "control_chain", "confirmation_source", "can_bind_entity" ], "additionalProperties": false }, "description": "The directors, owners of 25 percent or more, trust parties and signing officers, in order." }, "verified_by_user_id": { "nullable": true, "description": "The broker who last saved the verification.", "type": "string" }, "created_at": { "type": "string", "description": "When the verification was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "contact_id", "contact_name", "status", "registry_source", "record_type", "registration_number", "jurisdiction", "searched_at", "confirmation_measures", "unable_to_confirm_reason", "senior_managing_officer_name", "senior_managing_officer_title", "treated_as_high_risk", "no_owner_at_or_above_threshold", "authority_to_bind_confirmed", "authority_to_bind_basis", "controllers", "verified_by_user_id", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The party is not on the deal, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The party is a person, not a company (NOT_ENTITY).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/risk-assessment": { "get": { "operationId": "getDealRiskAssessment", "summary": "Read a deal's risk assessment", "description": "The FINTRAC risk assessment of the deal, as the broker fills it in on the deal's compliance tab: the reportable transaction types, the fraud and money-laundering questions, the FINTRAC report, and the broker's risk level for the transaction. This rates the transaction. The risk rating of each client is on `GET /deals/{id}/compliance`.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_risk_assessment", "description": "The type of this record. Always `deal_risk_assessment`.", "type": "string", "enum": [ "deal_risk_assessment" ] }, "id": { "type": "string", "description": "Stable identifier for the risk assessment. A deal has at most one." }, "deal_id": { "type": "string", "description": "The deal." }, "transaction_flags": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] }, "description": "The reportable transaction types, each answered `yes` or `no`. A question with no answer is absent. The keys: `suspicious_transaction`, `terrorist_property`, `large_cash_transaction`, `large_virtual_currency_transaction`." }, "fraud_answers": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] }, "description": "The fraud and money-laundering risk questions, each answered `yes` or `no`. `yes` is the answer to look at again, except for `prior_relationship`, `face_to_face_id`, and `canadian_resident`. A question with no answer is absent." }, "high_risk_neighbourhood": { "nullable": true, "description": "True when the property is in a high-risk neighbourhood. Null when not answered.", "type": "boolean" }, "report_status": { "nullable": true, "description": "Where the FINTRAC report is: `flagged`, `reported`, or `not_reported`. Null when not answered.", "type": "string", "enum": [ "flagged", "reported", "not_reported" ] }, "risk_level": { "nullable": true, "description": "The broker's risk level for the transaction. Null until the broker sets it.", "type": "string", "enum": [ "low", "medium", "high" ] }, "method_notes": { "nullable": true, "description": "How the broker reached the risk level.", "type": "string" }, "third_party_method_notes": { "nullable": true, "description": "What the broker did to find out if a third party is involved.", "type": "string" }, "pep_status": { "nullable": true, "description": "True when a politically exposed person is involved. Read only: it is filled from the client's application, or answered in BrokerPlus.", "type": "boolean" }, "pep_evaluation_method": { "nullable": true, "description": "How the politically exposed person question was answered.", "type": "string" }, "pep_source": { "nullable": true, "description": "Where `pep_status` came from, for example the client's application. Null when the broker answered it.", "type": "string" }, "identity_verified": { "nullable": true, "description": "The broker's statement that identity was verified for the deal. It does not clear the identity check of a party.", "type": "boolean" }, "identity_verification_method": { "nullable": true, "description": "How identity was verified, for example `verified_in_person`.", "type": "string", "enum": [ "verified_in_person", "handled_elsewhere", "client_provided", "other" ] }, "completed_at": { "nullable": true, "description": "When the broker marked the assessment complete. Null while it is open.", "type": "string" }, "rated_by_user_id": { "nullable": true, "description": "The broker who last saved it.", "type": "string" }, "rated_by_name": { "nullable": true, "description": "That broker's name.", "type": "string" }, "created_at": { "type": "string", "description": "When the assessment was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "transaction_flags", "fraud_answers", "high_risk_neighbourhood", "report_status", "risk_level", "method_notes", "third_party_method_notes", "pep_status", "pep_evaluation_method", "pep_source", "identity_verified", "identity_verification_method", "completed_at", "rated_by_user_id", "rated_by_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or it has no risk assessment yet (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "patch": { "operationId": "updateDealRiskAssessment", "summary": "Save a deal's risk assessment", "description": "Saves the FINTRAC risk assessment of the deal, as the broker does on the deal's compliance tab. It makes the assessment if the deal has none. Only the fields you send change, and the answers you send are added to the answers on file. The politically exposed person answer is read only.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_flags": { "description": "Answers to set, by question. The answers you do not send stay as they are.", "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] } }, "fraud_answers": { "description": "Answers to set, by question. The answers you do not send stay as they are. The keys: `prior_relationship`, `criminal_history`, `face_to_face_id`, `represented_by_intermediary`, `concealed_identity`, `large_transfers_unknown_source`, `broad_geographic_same_day`, `unusual_payment_methods`, `unjustified_cash`, `profile_cashflow_mismatch`, `unusual_for_occupation`, `unusual_for_history`, `sparse_records`, `anything_else_unusual`, `canadian_resident`, `near_border_crossing`, `organized_crime_area`, `high_crime_area`, `intermediary_holding_accounts`, `client_is_entity`, `offshore_interests`, `high_risk_countries`, `suspected_pep`, `unregistered_charity`.", "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] } }, "high_risk_neighbourhood": { "description": "True for a high-risk neighbourhood.", "nullable": true, "type": "boolean" }, "report_status": { "description": "Where the FINTRAC report is.", "nullable": true, "type": "string", "enum": [ "flagged", "reported", "not_reported" ] }, "risk_level": { "description": "The broker's risk level.", "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "method_notes": { "description": "How the broker reached the risk level.", "nullable": true, "type": "string", "maxLength": 4000 }, "third_party_method_notes": { "description": "What the broker did to find out if a third party is involved.", "nullable": true, "type": "string", "maxLength": 4000 }, "identity_verified": { "description": "True when identity was verified.", "nullable": true, "type": "boolean" }, "identity_verification_method": { "description": "How identity was verified.", "nullable": true, "type": "string", "enum": [ "verified_in_person", "handled_elsewhere", "client_provided", "other" ] }, "completed": { "description": "`true` marks the assessment complete now. `false` opens it again. Leave it out to keep it as it is.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "deal_risk_assessment", "description": "The type of this record. Always `deal_risk_assessment`.", "type": "string", "enum": [ "deal_risk_assessment" ] }, "id": { "type": "string", "description": "Stable identifier for the risk assessment. A deal has at most one." }, "deal_id": { "type": "string", "description": "The deal." }, "transaction_flags": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] }, "description": "The reportable transaction types, each answered `yes` or `no`. A question with no answer is absent. The keys: `suspicious_transaction`, `terrorist_property`, `large_cash_transaction`, `large_virtual_currency_transaction`." }, "fraud_answers": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "yes", "no" ] }, "description": "The fraud and money-laundering risk questions, each answered `yes` or `no`. `yes` is the answer to look at again, except for `prior_relationship`, `face_to_face_id`, and `canadian_resident`. A question with no answer is absent." }, "high_risk_neighbourhood": { "nullable": true, "description": "True when the property is in a high-risk neighbourhood. Null when not answered.", "type": "boolean" }, "report_status": { "nullable": true, "description": "Where the FINTRAC report is: `flagged`, `reported`, or `not_reported`. Null when not answered.", "type": "string", "enum": [ "flagged", "reported", "not_reported" ] }, "risk_level": { "nullable": true, "description": "The broker's risk level for the transaction. Null until the broker sets it.", "type": "string", "enum": [ "low", "medium", "high" ] }, "method_notes": { "nullable": true, "description": "How the broker reached the risk level.", "type": "string" }, "third_party_method_notes": { "nullable": true, "description": "What the broker did to find out if a third party is involved.", "type": "string" }, "pep_status": { "nullable": true, "description": "True when a politically exposed person is involved. Read only: it is filled from the client's application, or answered in BrokerPlus.", "type": "boolean" }, "pep_evaluation_method": { "nullable": true, "description": "How the politically exposed person question was answered.", "type": "string" }, "pep_source": { "nullable": true, "description": "Where `pep_status` came from, for example the client's application. Null when the broker answered it.", "type": "string" }, "identity_verified": { "nullable": true, "description": "The broker's statement that identity was verified for the deal. It does not clear the identity check of a party.", "type": "boolean" }, "identity_verification_method": { "nullable": true, "description": "How identity was verified, for example `verified_in_person`.", "type": "string", "enum": [ "verified_in_person", "handled_elsewhere", "client_provided", "other" ] }, "completed_at": { "nullable": true, "description": "When the broker marked the assessment complete. Null while it is open.", "type": "string" }, "rated_by_user_id": { "nullable": true, "description": "The broker who last saved it.", "type": "string" }, "rated_by_name": { "nullable": true, "description": "That broker's name.", "type": "string" }, "created_at": { "type": "string", "description": "When the assessment was first saved." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "deal_id", "transaction_flags", "fraud_answers", "high_risk_neighbourhood", "report_status", "risk_level", "method_notes", "third_party_method_notes", "pep_status", "pep_evaluation_method", "pep_source", "identity_verified", "identity_verification_method", "completed_at", "rated_by_user_id", "rated_by_name", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A question key is not known, or an answer is not `yes` or `no` (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist, or the broker cannot change it (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance/custom-obligations/{obligationId}/documents": { "post": { "operationId": "uploadComplianceEvidence", "summary": "Upload evidence for a custom requirement", "description": "Uploads a file to the deal and attaches it to one custom requirement of the deal's compliance checklist, as the requirement's upload button does. `obligationId` is `custom_obligation_id` in `document_requirements` of `GET /deals/{id}/compliance`. Send the file as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. The file is also a document on the deal. Nothing is sent.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "obligationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file. 50 MB maximum. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `paystub.pdf`." }, "content_type": { "type": "string", "minLength": 1, "description": "The MIME type of the file. Allowed: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV. A photo is stored as a one-page PDF." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "compliance_evidence", "description": "The type of this record. Always `compliance_evidence`.", "type": "string", "enum": [ "compliance_evidence" ] }, "id": { "type": "string", "description": "The document that answers the requirement. Read it with `GET /documents/{id}`." }, "deal_id": { "type": "string", "description": "The deal." }, "obligation_id": { "type": "string", "description": "The requirement it answers: `custom_obligation_id` in `document_requirements` of the checklist." }, "file_name": { "type": "string", "description": "The file name." }, "linked_at": { "type": "string", "description": "When the document was attached to the requirement." } }, "required": [ "object", "id", "deal_id", "obligation_id", "file_name", "linked_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing, its type is not allowed, or the base64 is not valid (VALIDATION_ERROR).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal or the requirement does not exist, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "The file is too large (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "The PDF is not readable (INVALID_PDF), or it has a password (LOCKED_PDF).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/compliance/custom-obligations/{obligationId}/documents/{documentId}": { "delete": { "operationId": "detachComplianceEvidence", "summary": "Take evidence off a custom requirement", "description": "Takes a document off a custom requirement of the deal's compliance checklist. The document stays on the deal: only the link to the requirement is removed.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "obligationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The requirement does not exist, the document is not attached to it, or the broker cannot change the deal (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/identity-verifications": { "get": { "operationId": "listDealIdentityVerifications", "summary": "List the identity verifications of a deal's parties", "description": "The identity verifications of the people on the deal, newest first, with the evidence each one examined. A verification belongs to the person, so one started from another deal is listed too. The document number is masked, and the images, the reports, and the credit file reference are not published. Reviewing a verification happens in BrokerPlus.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "identity_verification", "description": "The type of this record. Always `identity_verification`.", "type": "string", "enum": [ "identity_verification" ] }, "id": { "type": "string", "description": "Stable identifier for the verification." }, "contact_id": { "type": "string", "description": "The person who was verified. Resolve against `GET /contacts/{id}`." }, "contact_name": { "type": "string", "description": "The person's name, as the verification recorded it." }, "deal_id": { "nullable": true, "description": "The deal the verification was started from. A verification counts for the person on every deal.", "type": "string" }, "method": { "type": "string", "enum": [ "government_photo_id", "canadian_credit_file", "dual_process", "affiliate_member", "reliance" ], "description": "The FINTRAC method used to verify the identity." }, "provider": { "type": "string", "enum": [ "complycube", "manual" ], "description": "`complycube` for the online check, `manual` when the broker recorded it." }, "status": { "type": "string", "enum": [ "pending", "processing", "review_required", "verified", "failed", "cancelled" ], "description": "Where the verification is. `review_required` waits for the broker to review it in BrokerPlus." }, "verified_at": { "nullable": true, "description": "When the identity was verified. Null until it is.", "type": "string" }, "reviewed_at": { "nullable": true, "description": "When the broker reviewed it. Null if nobody did.", "type": "string" }, "failure_code": { "nullable": true, "description": "Why the verification failed, as a code.", "type": "string" }, "failure_reason": { "nullable": true, "description": "Why the verification failed, in words.", "type": "string" }, "evidence_sources": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "identity_evidence_source", "description": "The type of this record. Always `identity_evidence_source`.", "type": "string", "enum": [ "identity_evidence_source" ] }, "id": { "type": "string", "description": "Stable identifier for the source." }, "kind": { "type": "string", "enum": [ "government_document", "canadian_credit_file", "dual_process_source", "affiliate_record", "reliance_record" ], "description": "What the source is: a government ID document, a Canadian credit file, one of two dual-process sources, or a record from an affiliate or a reliance partner." }, "source_name": { "nullable": true, "description": "The name of the source, for example the bureau or the issuer.", "type": "string" }, "source_type": { "type": "string", "description": "The type of source, as the verification recorded it." }, "document_type": { "nullable": true, "description": "The type of ID document, for example `driving_license`.", "type": "string" }, "document_number": { "nullable": true, "description": "The number of the document, masked: only the last four characters show, for example `••••5678`.", "type": "string" }, "issuing_jurisdiction": { "nullable": true, "description": "The country or province that issued the document.", "type": "string" }, "document_expiry": { "nullable": true, "description": "When the document expires, as `YYYY-MM-DD`.", "type": "string" }, "confirmed_attributes": { "type": "array", "items": { "type": "string" }, "description": "What the source confirmed, for example `name`, `date_of_birth`, or `address`." }, "is_current": { "nullable": true, "description": "True when the source was current at the check.", "type": "boolean" }, "is_independent": { "nullable": true, "description": "True when the source is independent of the other source.", "type": "boolean" }, "file_age_months": { "nullable": true, "description": "How old the credit file is, in months.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "multi_source_confirmed": { "nullable": true, "description": "True when more than one source confirmed the information.", "type": "boolean" }, "authenticity_outcome": { "nullable": true, "description": "The result of the document authenticity check.", "type": "string" }, "liveness_outcome": { "nullable": true, "description": "The result of the liveness check on the photo.", "type": "string" }, "verified_at": { "type": "string", "description": "When the source was checked." } }, "required": [ "object", "id", "kind", "source_name", "source_type", "document_type", "document_number", "issuing_jurisdiction", "document_expiry", "confirmed_attributes", "is_current", "is_independent", "file_age_months", "multi_source_confirmed", "authenticity_outcome", "liveness_outcome", "verified_at" ], "additionalProperties": false }, "description": "The evidence the verification examined, in order. The images and the reports are not published." }, "created_at": { "type": "string", "description": "When the verification started." }, "updated_at": { "type": "string", "description": "Last change." } }, "required": [ "object", "id", "contact_id", "contact_name", "deal_id", "method", "provider", "status", "verified_at", "reviewed_at", "failure_code", "failure_reason", "evidence_sources", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The deal does not exist (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/deals/{id}/activity": { "get": { "operationId": "listDealActivity", "summary": "List a deal's activity", "description": "The activity trail of the deal, newest first: the messages and calls, the broker notes, and the changes to the deal. It holds the newest 200 entries of each kind. Read the detail with `record_type` and `record_id`.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only entries that happened at or after it. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "activity", "description": "The type of this record. Always `activity`.", "type": "string", "enum": [ "activity" ] }, "id": { "type": "string", "description": "The id of the message, the note, or the event." }, "kind": { "type": "string", "enum": [ "communication", "note", "event" ], "description": "`communication` is a message or a call, `note` is a broker note, and `event` is a change to a deal." }, "occurred_at": { "type": "string", "description": "When it happened." }, "summary": { "type": "string", "description": "One line, as the trail shows it: the subject of a message, or what changed, e.g. `Stage changed`." }, "preview": { "nullable": true, "description": "The start of the message or the note, as plain text, up to 280 characters. Null for an event.", "type": "string" }, "type": { "nullable": true, "description": "For an `event`, the change, e.g. `stage.transitioned` or `condition.satisfied`. Null otherwise.", "type": "string" }, "channel": { "nullable": true, "description": "For a `communication`: `email`, `sms`, `call`, or `meeting`.", "type": "string" }, "direction": { "nullable": true, "description": "For a `communication`: `inbound` or `outbound`.", "type": "string" }, "status": { "nullable": true, "description": "For a `communication`, its delivery state, e.g. `sent` or `failed`.", "type": "string" }, "actor_name": { "nullable": true, "description": "Who did it: the sender, the author, or the broker or automation that made the change.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it is on. Null for a message on no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "record_type": { "nullable": true, "description": "The record to read for the detail, e.g. `communication`, `note`, `condition`, or `deal`.", "type": "string" }, "record_id": { "nullable": true, "description": "The id of that record.", "type": "string" } }, "required": [ "object", "id", "kind", "occurred_at", "summary", "preview", "type", "channel", "direction", "status", "actor_name", "deal_id", "deal_name", "record_type", "record_id" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/contacts/{id}/activity": { "get": { "operationId": "listContactActivity", "summary": "List a contact's activity", "description": "The activity trail of a person across every deal, newest first: the messages and calls with them, and the changes to the deals that they are on. It holds the newest 200 entries of each kind.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only entries that happened at or after it. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "activity", "description": "The type of this record. Always `activity`.", "type": "string", "enum": [ "activity" ] }, "id": { "type": "string", "description": "The id of the message, the note, or the event." }, "kind": { "type": "string", "enum": [ "communication", "note", "event" ], "description": "`communication` is a message or a call, `note` is a broker note, and `event` is a change to a deal." }, "occurred_at": { "type": "string", "description": "When it happened." }, "summary": { "type": "string", "description": "One line, as the trail shows it: the subject of a message, or what changed, e.g. `Stage changed`." }, "preview": { "nullable": true, "description": "The start of the message or the note, as plain text, up to 280 characters. Null for an event.", "type": "string" }, "type": { "nullable": true, "description": "For an `event`, the change, e.g. `stage.transitioned` or `condition.satisfied`. Null otherwise.", "type": "string" }, "channel": { "nullable": true, "description": "For a `communication`: `email`, `sms`, `call`, or `meeting`.", "type": "string" }, "direction": { "nullable": true, "description": "For a `communication`: `inbound` or `outbound`.", "type": "string" }, "status": { "nullable": true, "description": "For a `communication`, its delivery state, e.g. `sent` or `failed`.", "type": "string" }, "actor_name": { "nullable": true, "description": "Who did it: the sender, the author, or the broker or automation that made the change.", "type": "string" }, "deal_id": { "nullable": true, "description": "The deal it is on. Null for a message on no deal.", "type": "string" }, "deal_name": { "nullable": true, "description": "The deal's name, for display.", "type": "string" }, "record_type": { "nullable": true, "description": "The record to read for the detail, e.g. `communication`, `note`, `condition`, or `deal`.", "type": "string" }, "record_id": { "nullable": true, "description": "The id of that record.", "type": "string" } }, "required": [ "object", "id", "kind", "occurred_at", "summary", "preview", "type", "channel", "direction", "status", "actor_name", "deal_id", "deal_name", "record_type", "record_id" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/rate-overrides": { "get": { "operationId": "listMyRateOverrides", "summary": "List the broker's own rates", "description": "The rates the broker set on the Rates page: a rate that replaces a live rate for one lender, term, and product, and every rate of a custom lender. Every rate is a PERCENT (`4.29` means 4.29%). A rate with `locked_by_brokerage` set to `true` is not used: the brokerage sets that rate for every broker.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "rate_override", "description": "The type of this record. Always `rate_override`.", "type": "string", "enum": [ "rate_override" ] }, "id": { "type": "string", "description": "Stable identifier for the rate." }, "lender_slug": { "type": "string", "description": "The lender. A lender BrokerPlus pulls rates for has its own slug, e.g. `rbc`. A custom lender has a slug that starts with `custom:`." }, "lender_name": { "nullable": true, "description": "The name of a custom lender. Null for a lender BrokerPlus pulls rates for.", "type": "string" }, "is_custom": { "type": "boolean", "description": "`true` for a lender the broker added. `false` for a rate that replaces the live rate of a lender BrokerPlus pulls." }, "lender_category": { "nullable": true, "description": "The kind of a custom lender. Null when not set.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85` means prime minus 0.85%. The rate then moves with prime. Null otherwise.", "type": "number" }, "original_rate": { "type": "number", "description": "The rate as the broker first entered it, as a PERCENT." }, "note": { "nullable": true, "description": "The broker's own note on the rate, e.g. `Promo to Friday, insured only`. Clients never see it.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the broker said the rate or its note stops being good. BrokerPlus only flags it.", "type": "string" }, "locked_by_brokerage": { "type": "boolean", "description": "`true` when the brokerage sets this lender, term, and product for every broker. The brokerage rate is then used, not this one." }, "created_at": { "type": "string", "description": "When the rate was first set." }, "updated_at": { "type": "string", "description": "When the rate last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "term_months", "product_type", "rate", "prime_offset", "original_rate", "note", "expires_at", "locked_by_brokerage", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setMyRateOverride", "summary": "Set one of the broker's rates", "description": "Sets the rate for one lender, term, and product, the same as a cell on the Rates page. Send `lender_slug` to replace the live rate of a lender BrokerPlus pulls, or `custom_lender_name` to set a rate for a custom lender. A rate that already exists for that lender, term, and product changes. Every rate is a PERCENT. The refinance, renewal, and penalty figures use the new rate when this call returns.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lender_slug": { "description": "A lender BrokerPlus pulls rates for, e.g. `rbc`. Send this or `custom_lender_name`, not both.", "type": "string", "minLength": 1, "maxLength": 64 }, "custom_lender_name": { "description": "The name of a custom lender. A name the broker already has, in any case, adds to that lender. A new name adds a lender.", "type": "string", "minLength": 1, "maxLength": 100 }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "description": "The rate as a PERCENT, e.g. `4.29`. Required unless you send `prime_offset`.", "type": "number", "minimum": 0, "maximum": 100 }, "prime_offset": { "description": "For a variable rate only: the difference from prime as a PERCENT, e.g. `-0.85`. BrokerPlus then calculates the rate from prime, and moves it when prime moves.", "nullable": true, "type": "number", "minimum": -10, "maximum": 10 }, "lender_category": { "description": "For a custom lender only: the kind of lender. Null clears it.", "nullable": true, "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "note": { "description": "The broker's own note on the rate. Leave it out to keep the current note. Null clears it.", "nullable": true, "type": "string", "maxLength": 500 }, "expires_at": { "description": "When the rate stops being good, as an ISO 8601 date. Leave it out to keep the current one. Null clears it.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] } }, "required": [ "term_months", "product_type" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "rate_override", "description": "The type of this record. Always `rate_override`.", "type": "string", "enum": [ "rate_override" ] }, "id": { "type": "string", "description": "Stable identifier for the rate." }, "lender_slug": { "type": "string", "description": "The lender. A lender BrokerPlus pulls rates for has its own slug, e.g. `rbc`. A custom lender has a slug that starts with `custom:`." }, "lender_name": { "nullable": true, "description": "The name of a custom lender. Null for a lender BrokerPlus pulls rates for.", "type": "string" }, "is_custom": { "type": "boolean", "description": "`true` for a lender the broker added. `false` for a rate that replaces the live rate of a lender BrokerPlus pulls." }, "lender_category": { "nullable": true, "description": "The kind of a custom lender. Null when not set.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85` means prime minus 0.85%. The rate then moves with prime. Null otherwise.", "type": "number" }, "original_rate": { "type": "number", "description": "The rate as the broker first entered it, as a PERCENT." }, "note": { "nullable": true, "description": "The broker's own note on the rate, e.g. `Promo to Friday, insured only`. Clients never see it.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the broker said the rate or its note stops being good. BrokerPlus only flags it.", "type": "string" }, "locked_by_brokerage": { "type": "boolean", "description": "`true` when the brokerage sets this lender, term, and product for every broker. The brokerage rate is then used, not this one." }, "created_at": { "type": "string", "description": "When the rate was first set." }, "updated_at": { "type": "string", "description": "When the rate last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "term_months", "product_type", "rate", "prime_offset", "original_rate", "note", "expires_at", "locked_by_brokerage", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/rate-overrides/{id}": { "delete": { "operationId": "deleteMyRateOverride", "summary": "Remove one of the broker's rates", "description": "Removes one rate. For a lender BrokerPlus pulls, the live rate is used again. For a custom lender, the lender has no rate for that term.", "tags": [ "Rates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/rate-overrides/reset": { "post": { "operationId": "resetMyRates", "summary": "Go back to live rates", "description": "Removes every rate the broker set for a lender BrokerPlus pulls, and every lender offset, so the live rates are used. Custom lenders and their rates stay. This is the same as Reset to Live Rates on the Rates page.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "overrides_deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates for lenders BrokerPlus pulls were removed." }, "offsets_deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many lender offsets were removed." } }, "required": [ "overrides_deleted", "offsets_deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/custom-lenders": { "post": { "operationId": "addMyCustomLenders", "summary": "Add custom lenders with their rates", "description": "Adds lenders that BrokerPlus does not pull rates for, each with a rate for one or more terms. A name the broker already has adds the rates to that lender. Every rate is a PERCENT.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lenders": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The lender's name. A name the broker already has, in any case, adds to that lender." }, "lender_category": { "description": "The kind of lender. Null clears it.", "nullable": true, "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "rates": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `6.89`." }, "prime_offset": { "description": "For a variable rate only: the difference from prime as a PERCENT. It wins over `rate`.", "nullable": true, "type": "number", "minimum": -10, "maximum": 10 } }, "required": [ "term_months", "product_type", "rate" ], "additionalProperties": false }, "description": "The lender's rates, one for each term. At most 12." } }, "required": [ "name", "rates" ], "additionalProperties": false }, "description": "The lenders to add, at most 25." } }, "required": [ "lenders" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "lenders": { "type": "array", "items": { "type": "object", "properties": { "lender_slug": { "type": "string", "description": "The custom lender's slug. Use it to rename the lender." }, "name": { "type": "string", "description": "The lender's name." } }, "required": [ "lender_slug", "name" ], "additionalProperties": false }, "description": "The lenders, in the order you sent them." }, "rates_set": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates were set across all the lenders." } }, "required": [ "lenders", "rates_set" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/custom-lenders/{lenderSlug}": { "patch": { "operationId": "renameMyCustomLender", "summary": "Rename a custom lender", "description": "Gives a custom lender a new name on every one of its rates. Its slug does not change.", "tags": [ "Rates" ], "parameters": [ { "name": "lenderSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The new name for the custom lender." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "lender_slug": { "type": "string", "description": "The custom lender's slug. It does not change." }, "name": { "type": "string", "description": "The new name." }, "rates_changed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many of the lender's rates now carry the new name." } }, "required": [ "lender_slug", "name", "rates_changed" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The broker has no custom lender with this slug (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/lender-offsets": { "get": { "operationId": "listMyLenderOffsets", "summary": "List the broker's lender offsets", "description": "The offsets the broker set for a lender: a number of BASIS POINTS added to every live rate of that lender. A rate set for one term wins over the offset.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "lender_offset", "description": "The type of this record. Always `lender_offset`.", "type": "string", "enum": [ "lender_offset" ] }, "id": { "type": "string", "description": "Stable identifier for the offset." }, "lender_slug": { "type": "string", "description": "The lender BrokerPlus pulls rates for, e.g. `rbc`." }, "offset_bps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "BASIS POINTS added to every live rate of the lender, e.g. `-10` means 0.10% below. A rate set for one term wins over the offset." }, "created_at": { "type": "string", "description": "When the offset was first set." }, "updated_at": { "type": "string", "description": "When the offset last changed." } }, "required": [ "object", "id", "lender_slug", "offset_bps", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setMyLenderOffset", "summary": "Set a lender offset", "description": "Sets the offset, in BASIS POINTS, for one lender BrokerPlus pulls rates for. An offset that already exists for the lender changes. A custom lender cannot have an offset.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lender_slug": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A lender BrokerPlus pulls rates for, e.g. `rbc`. Not a custom lender." }, "offset_bps": { "type": "integer", "minimum": -500, "maximum": 500, "description": "BASIS POINTS from -500 to 500, not 0. `-10` means 0.10% below the live rate." } }, "required": [ "lender_slug", "offset_bps" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lender_offset", "description": "The type of this record. Always `lender_offset`.", "type": "string", "enum": [ "lender_offset" ] }, "id": { "type": "string", "description": "Stable identifier for the offset." }, "lender_slug": { "type": "string", "description": "The lender BrokerPlus pulls rates for, e.g. `rbc`." }, "offset_bps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "BASIS POINTS added to every live rate of the lender, e.g. `-10` means 0.10% below. A rate set for one term wins over the offset." }, "created_at": { "type": "string", "description": "When the offset was first set." }, "updated_at": { "type": "string", "description": "When the offset last changed." } }, "required": [ "object", "id", "lender_slug", "offset_bps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/me/lender-offsets/{lenderSlug}": { "delete": { "operationId": "deleteMyLenderOffset", "summary": "Remove a lender offset", "description": "Removes the offset for one lender. Its live rates are used as they are.", "tags": [ "Rates" ], "parameters": [ { "name": "lenderSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No offset is set for this lender (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/brokerage/rate-overrides": { "get": { "operationId": "listBrokerageRateOverrides", "summary": "List the brokerage's rates", "description": "The rates the brokerage set for every broker on the brokerage Rates page: a rate that replaces a live rate for one lender, term, and product, and every rate of a brokerage custom lender. A broker's own rate for the same lender, term, and product is not used while the brokerage sets one. Every rate is a PERCENT (`4.29` means 4.29%). Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "brokerage_rate_override", "description": "The type of this record. Always `brokerage_rate_override`.", "type": "string", "enum": [ "brokerage_rate_override" ] }, "id": { "type": "string", "description": "Stable identifier for the rate." }, "lender_slug": { "type": "string", "description": "The lender, e.g. `rbc`. A custom lender has a slug that starts with `custom:`." }, "lender_name": { "nullable": true, "description": "The name of a custom lender. Null for a lender BrokerPlus pulls rates for.", "type": "string" }, "is_custom": { "type": "boolean", "description": "`true` for a lender the brokerage added." }, "lender_category": { "nullable": true, "description": "The kind of a custom lender. Null when not set.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "original_rate": { "type": "number", "description": "The rate as the brokerage first entered it, as a PERCENT." }, "note": { "nullable": true, "description": "The brokerage's note on the rate. Every broker in the brokerage can read it. Clients never see it.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the brokerage said the rate or its note stops being good. BrokerPlus only flags it.", "type": "string" }, "created_at": { "type": "string", "description": "When the rate was first set." }, "updated_at": { "type": "string", "description": "When the rate last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "term_months", "product_type", "rate", "original_rate", "note", "expires_at", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setBrokerageRateOverride", "summary": "Set one of the brokerage's rates", "description": "Sets the brokerage's rate for one lender, term, and product, for every broker. Send `lender_slug` to replace the live rate of a lender BrokerPlus pulls, or `custom_lender_name` for a brokerage custom lender. A rate that already exists for that lender, term, and product changes. Every rate is a PERCENT. Every broker's refinance, renewal, and penalty figures use the new rate when this call returns. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lender_slug": { "description": "A lender BrokerPlus pulls rates for, e.g. `rbc`. Send this or `custom_lender_name`, not both.", "type": "string", "minLength": 1, "maxLength": 64 }, "custom_lender_name": { "description": "The name of a custom lender. A name the brokerage already has, in any case, adds to that lender.", "type": "string", "minLength": 1, "maxLength": 100 }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The rate as a PERCENT, e.g. `4.19`." }, "lender_category": { "description": "For a custom lender only: the kind of lender. Null clears it.", "nullable": true, "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "note": { "description": "A note every broker can read. Leave it out to keep the current note. Null clears it.", "nullable": true, "type": "string", "maxLength": 500 }, "expires_at": { "description": "When the rate stops being good, as an ISO 8601 date. Leave it out to keep the current one. Null clears it.", "nullable": true, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } ] } }, "required": [ "term_months", "product_type", "rate" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "brokerage_rate_override", "description": "The type of this record. Always `brokerage_rate_override`.", "type": "string", "enum": [ "brokerage_rate_override" ] }, "id": { "type": "string", "description": "Stable identifier for the rate." }, "lender_slug": { "type": "string", "description": "The lender, e.g. `rbc`. A custom lender has a slug that starts with `custom:`." }, "lender_name": { "nullable": true, "description": "The name of a custom lender. Null for a lender BrokerPlus pulls rates for.", "type": "string" }, "is_custom": { "type": "boolean", "description": "`true` for a lender the brokerage added." }, "lender_category": { "nullable": true, "description": "The kind of a custom lender. Null when not set.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months: 1 to 600 for a fixed rate, `0` for a variable rate, or `-1` for a rental rate." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed`, `variable`, or `rental`." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "original_rate": { "type": "number", "description": "The rate as the brokerage first entered it, as a PERCENT." }, "note": { "nullable": true, "description": "The brokerage's note on the rate. Every broker in the brokerage can read it. Clients never see it.", "type": "string" }, "expires_at": { "nullable": true, "description": "When the brokerage said the rate or its note stops being good. BrokerPlus only flags it.", "type": "string" }, "created_at": { "type": "string", "description": "When the rate was first set." }, "updated_at": { "type": "string", "description": "When the rate last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "term_months", "product_type", "rate", "original_rate", "note", "expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/brokerage/rate-overrides/{id}": { "delete": { "operationId": "deleteBrokerageRateOverride", "summary": "Remove one of the brokerage's rates", "description": "Removes one brokerage rate. Each broker's own rate or the live rate is used again. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The brokerage has no rate with this ID (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/brokerage/rate-overrides/reset": { "post": { "operationId": "resetBrokerageRates", "summary": "Go back to live rates for the brokerage", "description": "Removes every brokerage rate for a lender BrokerPlus pulls, and every brokerage lender offset. Brokerage custom lenders and their rates stay. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "overrides_deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates for lenders BrokerPlus pulls were removed." }, "offsets_deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many lender offsets were removed." } }, "required": [ "overrides_deleted", "offsets_deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/brokerage/lender-offsets": { "get": { "operationId": "listBrokerageLenderOffsets", "summary": "List the brokerage's lender offsets", "description": "The offsets the brokerage set for a lender: a number of BASIS POINTS added to every live rate of that lender for every broker. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "brokerage_lender_offset", "description": "The type of this record. Always `brokerage_lender_offset`.", "type": "string", "enum": [ "brokerage_lender_offset" ] }, "id": { "type": "string", "description": "Stable identifier for the offset." }, "lender_slug": { "type": "string", "description": "The lender BrokerPlus pulls rates for, e.g. `rbc`." }, "offset_bps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "BASIS POINTS added to every live rate of the lender for every broker, e.g. `-10` means 0.10% below. It wins over a broker's own offset for the lender." }, "created_at": { "type": "string", "description": "When the offset was first set." }, "updated_at": { "type": "string", "description": "When the offset last changed." } }, "required": [ "object", "id", "lender_slug", "offset_bps", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setBrokerageLenderOffset", "summary": "Set a brokerage lender offset", "description": "Sets the brokerage's offset, in BASIS POINTS, for one lender BrokerPlus pulls rates for. An offset that already exists for the lender changes. A custom lender cannot have an offset. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lender_slug": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A lender BrokerPlus pulls rates for, e.g. `rbc`. Not a custom lender." }, "offset_bps": { "type": "integer", "minimum": -500, "maximum": 500, "description": "BASIS POINTS from -500 to 500, not 0. `-10` means 0.10% below the live rate." } }, "required": [ "lender_slug", "offset_bps" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "brokerage_lender_offset", "description": "The type of this record. Always `brokerage_lender_offset`.", "type": "string", "enum": [ "brokerage_lender_offset" ] }, "id": { "type": "string", "description": "Stable identifier for the offset." }, "lender_slug": { "type": "string", "description": "The lender BrokerPlus pulls rates for, e.g. `rbc`." }, "offset_bps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "BASIS POINTS added to every live rate of the lender for every broker, e.g. `-10` means 0.10% below. It wins over a broker's own offset for the lender." }, "created_at": { "type": "string", "description": "When the offset was first set." }, "updated_at": { "type": "string", "description": "When the offset last changed." } }, "required": [ "object", "id", "lender_slug", "offset_bps", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/brokerage/lender-offsets/{lenderSlug}": { "delete": { "operationId": "deleteBrokerageLenderOffset", "summary": "Remove a brokerage lender offset", "description": "Removes the brokerage's offset for one lender. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "lenderSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The brokerage has no offset for this lender (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lender-cashback": { "get": { "operationId": "listLenderCashback", "summary": "List lender cashback", "description": "The cashback each lender pays at closing, as the opportunity figures use it: the brokerage's own rule where it set one, else the one BrokerPlus keeps. `cashback_percent` is a PERCENT of the balance (`1` means 1%), and `rate_premium_bps` is in BASIS POINTS. The `id` is the lender's slug.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "lender_cashback", "description": "The type of this record. Always `lender_cashback`.", "type": "string", "enum": [ "lender_cashback" ] }, "id": { "type": "string", "description": "The lender's slug, e.g. `td`. There is one cashback rule per lender." }, "lender_slug": { "type": "string", "description": "The lender, e.g. `td`." }, "source": { "type": "string", "enum": [ "default", "override" ], "description": "`default` for the cashback BrokerPlus keeps for the lender, `override` for the brokerage's own." }, "cashback_percent": { "type": "number", "description": "Cashback as a PERCENT of the mortgage balance, e.g. `1` means 1%. `0` when the lender pays a flat amount." }, "flat_amount": { "nullable": true, "description": "A flat cashback in dollars, e.g. `5100`. When set, it wins over `cashback_percent`.", "type": "number" }, "min_balance": { "nullable": true, "description": "The smallest balance, in dollars, the cashback applies to. Null for none.", "type": "number" }, "max_balance": { "nullable": true, "description": "The largest balance, in dollars, the cashback applies to. Null for none.", "type": "number" }, "rate_premium_bps": { "nullable": true, "description": "BASIS POINTS the cashback product usually costs over the lender's best rate, e.g. `20`. BrokerPlus warns with it and does not change the rate.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notes": { "nullable": true, "description": "Where BrokerPlus's default came from. Null for the brokerage's own.", "type": "string" } }, "required": [ "object", "id", "lender_slug", "source", "cashback_percent", "flat_amount", "min_balance", "max_balance", "rate_premium_bps", "notes" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "setLenderCashback", "summary": "Set the brokerage's cashback for a lender", "description": "Sets the brokerage's own cashback for one lender, in place of the one BrokerPlus keeps. It applies to every client whose best option is that lender. Send `cashback_percent` as a PERCENT, or `flat_amount` in dollars. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lender_slug": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The lender, e.g. `td`." }, "cashback_percent": { "default": 0, "description": "Cashback as a PERCENT of the balance, from 0 to 20, e.g. `1` for 1%. Defaults to 0.", "type": "number", "minimum": 0, "maximum": 20 }, "flat_amount": { "description": "A flat cashback in dollars, up to 100,000. When set, it wins over `cashback_percent`.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100000 }, "min_balance": { "description": "The smallest balance, in dollars, it applies to.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100000000 }, "max_balance": { "description": "The largest balance, in dollars, it applies to.", "nullable": true, "type": "number", "minimum": 0, "maximum": 100000000 }, "rate_premium_bps": { "description": "BASIS POINTS the product costs over the best rate, from 0 to 500.", "nullable": true, "type": "integer", "minimum": 0, "maximum": 500 } }, "required": [ "lender_slug", "cashback_percent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "lender_cashback", "description": "The type of this record. Always `lender_cashback`.", "type": "string", "enum": [ "lender_cashback" ] }, "id": { "type": "string", "description": "The lender's slug, e.g. `td`. There is one cashback rule per lender." }, "lender_slug": { "type": "string", "description": "The lender, e.g. `td`." }, "source": { "type": "string", "enum": [ "default", "override" ], "description": "`default` for the cashback BrokerPlus keeps for the lender, `override` for the brokerage's own." }, "cashback_percent": { "type": "number", "description": "Cashback as a PERCENT of the mortgage balance, e.g. `1` means 1%. `0` when the lender pays a flat amount." }, "flat_amount": { "nullable": true, "description": "A flat cashback in dollars, e.g. `5100`. When set, it wins over `cashback_percent`.", "type": "number" }, "min_balance": { "nullable": true, "description": "The smallest balance, in dollars, the cashback applies to. Null for none.", "type": "number" }, "max_balance": { "nullable": true, "description": "The largest balance, in dollars, the cashback applies to. Null for none.", "type": "number" }, "rate_premium_bps": { "nullable": true, "description": "BASIS POINTS the cashback product usually costs over the lender's best rate, e.g. `20`. BrokerPlus warns with it and does not change the rate.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notes": { "nullable": true, "description": "Where BrokerPlus's default came from. Null for the brokerage's own.", "type": "string" } }, "required": [ "object", "id", "lender_slug", "source", "cashback_percent", "flat_amount", "min_balance", "max_balance", "rate_premium_bps", "notes" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/lender-cashback/{lenderSlug}": { "delete": { "operationId": "deleteLenderCashback", "summary": "Go back to BrokerPlus's cashback for a lender", "description": "Removes the brokerage's own cashback for one lender, so the one BrokerPlus keeps applies again. Only a key that belongs to a brokerage admin can call this.", "tags": [ "Rates" ], "parameters": [ { "name": "lenderSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "403": { "description": "The key's broker is not a brokerage admin (FORBIDDEN).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "The brokerage has no cashback of its own for this lender (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/rate-sheets": { "get": { "operationId": "listRateSheets", "summary": "List rate sheets", "description": "The lender rate sheets uploaded in the brokerage, newest first, each with the rates BrokerPlus read from it. Every rate is a PERCENT (`4.29` means 4.29%). The file itself is not returned.", "tags": [ "Rates" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "1-indexed page number, up to 1000000." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Rows per page. Capped at 100." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 date-time, for example `2026-10-01T00:00:00Z`. Returns only rows changed at or after it, in `updated_at` order and then `id` order, oldest first. A value that is not ISO 8601 gets `400 VALIDATION_ERROR`." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use with `updated_since` to read the next page of a sync. Send the `updated_at` and `id` of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep `page` at 1. Without `updated_since` it gets `400 VALIDATION_ERROR`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "default": "rate_sheet", "description": "The type of this record. Always `rate_sheet`.", "type": "string", "enum": [ "rate_sheet" ] }, "id": { "type": "string", "description": "Stable identifier for the rate sheet." }, "lender_slug": { "type": "string", "description": "The lender the sheet is filed under, e.g. `rbc`. A lender BrokerPlus does not know starts with `custom:`." }, "lender_name": { "type": "string", "description": "The lender's name." }, "is_custom": { "type": "boolean", "description": "`true` when the sheet is filed under a custom lender." }, "lender_category": { "nullable": true, "description": "The kind of lender. Null when not known.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "effective_date": { "nullable": true, "description": "The date printed on the sheet, as `YYYY-MM-DD`. Null when BrokerPlus could not read one.", "type": "string" }, "file_name": { "type": "string", "description": "The name of the uploaded file." }, "status": { "type": "string", "enum": [ "pending", "parsed", "failed", "applied" ], "description": "`parsed` once BrokerPlus has read its rates, `applied` once they are on the broker's rates." }, "parse_error": { "nullable": true, "description": "Why BrokerPlus could not read the sheet. Null otherwise.", "type": "string" }, "applied_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates the last apply put on the broker's rates." }, "rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the row." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed` or `variable`." }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months. `0` for a variable rate." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet, e.g. `5yr Fixed High-Ratio`.", "type": "string" } }, "required": [ "id", "product_type", "term_months", "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate BrokerPlus read from the sheet." }, "created_at": { "type": "string", "description": "When the sheet was uploaded." }, "updated_at": { "type": "string", "description": "When the sheet last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "effective_date", "file_name", "status", "parse_error", "applied_count", "rates", "created_at", "updated_at" ], "additionalProperties": false }, "description": "The page of results. The endpoint description and the Pagination guide give the order." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total matching records across every page." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The page you are on, 1-based." }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many records this page can hold." }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages at the current page_size." } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false, "description": "Offset pagination. Page forward until `page` reaches `total_pages`." } }, "required": [ "success", "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "post": { "operationId": "uploadRateSheet", "summary": "Upload a rate sheet", "description": "Send a lender's rate sheet as `multipart/form-data` in a `file` field, or as JSON with `content_base64`. BrokerPlus reads the lender, the date, and every rate on it, and answers with them and the proposed `mapping`. Nothing changes on the broker's rates until you apply the sheet.", "tags": [ "Rates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The rate sheet. 50 MB maximum. Allowed: PDF, PNG, JPEG, WebP, or Word (.docx)." } }, "required": [ "file" ], "additionalProperties": false } }, "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The filename, with its extension, e.g. `rbc-rates.pdf`." }, "content_type": { "type": "string", "minLength": 1, "description": "The MIME type of the file. Allowed: PDF, PNG, JPEG, WebP, or Word (.docx)." }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 13981016, "description": "The file, base64-encoded. 10 MB maximum before encoding. Send a larger file as `multipart/form-data`." } }, "required": [ "file_name", "content_type", "content_base64" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "rate_sheet", "description": "The type of this record. Always `rate_sheet`.", "type": "string", "enum": [ "rate_sheet" ] }, "id": { "type": "string", "description": "Stable identifier for the rate sheet." }, "lender_slug": { "type": "string", "description": "The lender the sheet is filed under, e.g. `rbc`. A lender BrokerPlus does not know starts with `custom:`." }, "lender_name": { "type": "string", "description": "The lender's name." }, "is_custom": { "type": "boolean", "description": "`true` when the sheet is filed under a custom lender." }, "lender_category": { "nullable": true, "description": "The kind of lender. Null when not known.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "effective_date": { "nullable": true, "description": "The date printed on the sheet, as `YYYY-MM-DD`. Null when BrokerPlus could not read one.", "type": "string" }, "file_name": { "type": "string", "description": "The name of the uploaded file." }, "status": { "type": "string", "enum": [ "pending", "parsed", "failed", "applied" ], "description": "`parsed` once BrokerPlus has read its rates, `applied` once they are on the broker's rates." }, "parse_error": { "nullable": true, "description": "Why BrokerPlus could not read the sheet. Null otherwise.", "type": "string" }, "applied_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates the last apply put on the broker's rates." }, "rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the row." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed` or `variable`." }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months. `0` for a variable rate." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet, e.g. `5yr Fixed High-Ratio`.", "type": "string" } }, "required": [ "id", "product_type", "term_months", "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate BrokerPlus read from the sheet." }, "created_at": { "type": "string", "description": "When the sheet was uploaded." }, "updated_at": { "type": "string", "description": "When the sheet last changed." }, "mapping": { "type": "array", "items": { "type": "object", "properties": { "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "A term on the Rates page: `0` (variable), 12, 24, 36, 48, or 60." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "rental" ], "description": "`fixed` or `variable`." }, "label": { "type": "string", "description": "The cell on the Rates page, e.g. `5yr Fixed`." }, "options": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet.", "type": "string" } }, "required": [ "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate on the sheet for this term, the one BrokerPlus suggests first. Empty when none." }, "suggested_index": { "nullable": true, "description": "Which option BrokerPlus suggests, an index into `options`. Null when there are none.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "term_months", "product_type", "label", "options", "suggested_index" ], "additionalProperties": false }, "description": "The rates BrokerPlus proposes for each cell of the Rates page. Pick from it to build an apply." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "effective_date", "file_name", "status", "parse_error", "applied_count", "rates", "created_at", "updated_at", "mapping" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "The file is missing or not valid base64 (VALIDATION_ERROR), its type is not a PDF, image, or Word file (UNSUPPORTED_TYPE), or it is too large (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "413": { "description": "A base64 file is larger than its limit (FILE_TOO_LARGE).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "BrokerPlus could not read any rates from the file (PARSE_FAILED or NO_RATES_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/rate-sheets/{id}": { "get": { "operationId": "getRateSheet", "summary": "Get a rate sheet", "description": "One rate sheet with the rates BrokerPlus read from it, and `mapping`: the rates it proposes for each cell of the Rates page. Build an apply from `mapping`.", "tags": [ "Rates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "rate_sheet", "description": "The type of this record. Always `rate_sheet`.", "type": "string", "enum": [ "rate_sheet" ] }, "id": { "type": "string", "description": "Stable identifier for the rate sheet." }, "lender_slug": { "type": "string", "description": "The lender the sheet is filed under, e.g. `rbc`. A lender BrokerPlus does not know starts with `custom:`." }, "lender_name": { "type": "string", "description": "The lender's name." }, "is_custom": { "type": "boolean", "description": "`true` when the sheet is filed under a custom lender." }, "lender_category": { "nullable": true, "description": "The kind of lender. Null when not known.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "effective_date": { "nullable": true, "description": "The date printed on the sheet, as `YYYY-MM-DD`. Null when BrokerPlus could not read one.", "type": "string" }, "file_name": { "type": "string", "description": "The name of the uploaded file." }, "status": { "type": "string", "enum": [ "pending", "parsed", "failed", "applied" ], "description": "`parsed` once BrokerPlus has read its rates, `applied` once they are on the broker's rates." }, "parse_error": { "nullable": true, "description": "Why BrokerPlus could not read the sheet. Null otherwise.", "type": "string" }, "applied_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates the last apply put on the broker's rates." }, "rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the row." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed` or `variable`." }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months. `0` for a variable rate." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet, e.g. `5yr Fixed High-Ratio`.", "type": "string" } }, "required": [ "id", "product_type", "term_months", "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate BrokerPlus read from the sheet." }, "created_at": { "type": "string", "description": "When the sheet was uploaded." }, "updated_at": { "type": "string", "description": "When the sheet last changed." }, "mapping": { "type": "array", "items": { "type": "object", "properties": { "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "A term on the Rates page: `0` (variable), 12, 24, 36, 48, or 60." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "rental" ], "description": "`fixed` or `variable`." }, "label": { "type": "string", "description": "The cell on the Rates page, e.g. `5yr Fixed`." }, "options": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet.", "type": "string" } }, "required": [ "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate on the sheet for this term, the one BrokerPlus suggests first. Empty when none." }, "suggested_index": { "nullable": true, "description": "Which option BrokerPlus suggests, an index into `options`. Null when there are none.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "term_months", "product_type", "label", "options", "suggested_index" ], "additionalProperties": false }, "description": "The rates BrokerPlus proposes for each cell of the Rates page. Pick from it to build an apply." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "effective_date", "file_name", "status", "parse_error", "applied_count", "rates", "created_at", "updated_at", "mapping" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No rate sheet in the brokerage has this ID (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } }, "delete": { "operationId": "deleteRateSheet", "summary": "Delete a rate sheet", "description": "Deletes the sheet and its file. The rates it put on the broker's rates stay, because the broker may have changed them since.", "tags": [ "Rates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The record that was deleted." }, "deleted": { "type": "boolean", "description": "Always `true`. The delete is idempotent." } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No rate sheet in the brokerage has this ID (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } }, "/rate-sheets/{id}/apply": { "post": { "operationId": "applyRateSheet", "summary": "Put a rate sheet's rates on the broker's rates", "description": "Sets the broker's own rate for each row you send, under the sheet's lender, the same as confirming a sheet on the Rates page. Send `lender` to file them under another lender: `{ \"slug\": \"rbc\" }`, or `{ \"slug\": null, \"name\": \"Beacon Trust\" }` for a custom lender. Every rate is a PERCENT. The refinance, renewal, and penalty figures use the new rates when this call returns.", "tags": [ "Rates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource id." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "A term on the Rates page: `0` (variable), 12, 24, 36, 48, or 60." }, "product_type": { "type": "string", "enum": [ "fixed", "variable" ], "description": "`fixed` or `variable`." }, "rate": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "exclusiveMaximum": true, "description": "The rate as a PERCENT, e.g. `4.29`." }, "prime_offset": { "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`.", "nullable": true, "type": "number", "minimum": -10, "maximum": 10 } }, "required": [ "term_months", "product_type", "rate" ], "additionalProperties": false }, "description": "The rates to put on the broker's rates, one per cell. Leave a cell out to keep what is there." }, "lender": { "description": "File the rates under another lender than the one BrokerPlus read from the sheet.", "type": "object", "properties": { "slug": { "nullable": true, "description": "A lender BrokerPlus pulls rates for, e.g. `rbc`, or null for a custom one.", "type": "string" }, "name": { "description": "The custom lender's name, with `slug` null.", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "slug" ], "additionalProperties": false }, "lender_category": { "description": "For a custom lender only: the kind of lender. Null clears it.", "nullable": true, "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] } }, "required": [ "rows" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `true` on a successful response." }, "data": { "type": "object", "properties": { "object": { "default": "rate_sheet", "description": "The type of this record. Always `rate_sheet`.", "type": "string", "enum": [ "rate_sheet" ] }, "id": { "type": "string", "description": "Stable identifier for the rate sheet." }, "lender_slug": { "type": "string", "description": "The lender the sheet is filed under, e.g. `rbc`. A lender BrokerPlus does not know starts with `custom:`." }, "lender_name": { "type": "string", "description": "The lender's name." }, "is_custom": { "type": "boolean", "description": "`true` when the sheet is filed under a custom lender." }, "lender_category": { "nullable": true, "description": "The kind of lender. Null when not known.", "type": "string", "enum": [ "a_lender", "alt_lender", "private", "reverse" ] }, "effective_date": { "nullable": true, "description": "The date printed on the sheet, as `YYYY-MM-DD`. Null when BrokerPlus could not read one.", "type": "string" }, "file_name": { "type": "string", "description": "The name of the uploaded file." }, "status": { "type": "string", "enum": [ "pending", "parsed", "failed", "applied" ], "description": "`parsed` once BrokerPlus has read its rates, `applied` once they are on the broker's rates." }, "parse_error": { "nullable": true, "description": "Why BrokerPlus could not read the sheet. Null otherwise.", "type": "string" }, "applied_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rates the last apply put on the broker's rates." }, "rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the row." }, "product_type": { "type": "string", "enum": [ "fixed", "variable", "arm", "prime", "rental" ], "description": "The product: `fixed` or `variable`." }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The term in months. `0` for a variable rate." }, "rate": { "type": "number", "description": "An annual rate as a PERCENT, e.g. `4.29` means 4.29%. Not a fraction." }, "prime_offset": { "nullable": true, "description": "For a variable rate, the difference from prime as a PERCENT, e.g. `-0.85`. Null for a fixed rate.", "type": "number" }, "rate_type": { "nullable": true, "description": "The qualifier printed on the sheet: `insured`, `insurable`, `uninsured`, `conventional`, or null.", "type": "string" }, "label": { "nullable": true, "description": "The product as printed on the sheet, e.g. `5yr Fixed High-Ratio`.", "type": "string" } }, "required": [ "id", "product_type", "term_months", "rate", "prime_offset", "rate_type", "label" ], "additionalProperties": false }, "description": "Every rate BrokerPlus read from the sheet." }, "created_at": { "type": "string", "description": "When the sheet was uploaded." }, "updated_at": { "type": "string", "description": "When the sheet last changed." } }, "required": [ "object", "id", "lender_slug", "lender_name", "is_custom", "lender_category", "effective_date", "file_name", "status", "parse_error", "applied_count", "rates", "created_at", "updated_at" ], "additionalProperties": false, "description": "The requested record." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "A row has a term that is not on the Rates page (BAD_TERM), or `lender` names no lender BrokerPlus pulls (BAD_LENDER) (VALIDATION_ERROR for the body).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "404": { "description": "No rate sheet in the brokerage has this ID (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "409": { "description": "The reservation is in progress, belongs to another API key or broker, or has no identifiable owner. Wait before a same-key retry of an in-progress request. Reconcile the original result before you use a new key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "422": { "description": "This Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` on an error response." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change at any time." }, "details": { "description": "Present on validation errors: which fields failed and why." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "What went wrong. `code` is the part that is safe to branch on." } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Every 4xx/5xx response uses this envelope." } } } } } } } } }