Suggestions

List suggestions

GET

https://api.mos.getbrokerplus.ca/v1

/suggestions

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.

List suggestions › query Parameters

page

integer · min: 1 · max: 1000000

1-indexed page number, up to 1000000.

Default: 1

page_size

integer · min: 1 · max: 100

Rows per page. Capped at 100.

Default: 50

updated_since

string · date-time

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.

after_id

string

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.

status

string · enum

Return only suggestions in this state. Send pending for the ones that wait for a decision.

Enum values:

pending

stale

dismissed

executed

cancelled

deal_id

string

Return only suggestions about this deal.

List suggestions › Responses

Success

success

boolean · required

Always true on a successful response.

object[] · required

The page of results. The endpoint description and the Pagination guide give the order.

object · required

Offset pagination. Page forward until page reaches total_pages.

GET/suggestions

curl https://api.mos.getbrokerplus.ca/v1/suggestions \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "object": "suggestion",
      "id": "id",
      "kind": "kind",
      "title": "title",
      "status": "pending",
      "values": {
        "key": "string"
      },
      "approvable": true,
      "deal_id": "deal_id",
      "deal_name": "deal_name",
      "subject_type": "subject_type",
      "subject_id": "subject_id",
      "bundle_key": "bundle_key",
      "bundle_label": "bundle_label",
      "task_id": "task_id",
      "created_by_agent": true,
      "expires_at": "expires_at",
      "dismissed_at": "dismissed_at",
      "dismiss_reason": "dismiss_reason",
      "executed_at": "executed_at",
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ],
  "pagination": {
    "total": 0,
    "page": 0,
    "page_size": 0,
    "total_pages": 0
  }
}

json

application/json

Retrieve a suggestion

GET

https://api.mos.getbrokerplus.ca/v1

/suggestions/{id}

One suggestion, its values, and whether your key can approve it.

Retrieve a suggestion › path Parameters

id

string · required

Resource id.

Retrieve a suggestion › Responses

Success

success

boolean · required

Always true on a successful response.

object · required

The requested record.

GET/suggestions/{id}

curl https://api.mos.getbrokerplus.ca/v1/suggestions/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "object": "suggestion",
    "id": "id",
    "kind": "kind",
    "title": "title",
    "status": "pending",
    "values": {
      "key": "string"
    },
    "approvable": true,
    "deal_id": "deal_id",
    "deal_name": "deal_name",
    "subject_type": "subject_type",
    "subject_id": "subject_id",
    "bundle_key": "bundle_key",
    "bundle_label": "bundle_label",
    "task_id": "task_id",
    "created_by_agent": true,
    "expires_at": "expires_at",
    "dismissed_at": "dismissed_at",
    "dismiss_reason": "dismiss_reason",
    "executed_at": "executed_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Approve a suggestion

POST

https://api.mos.getbrokerplus.ca/v1

/suggestions/{id}/approve

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.

Approve a suggestion › path Parameters

id

string · required

Resource id.

Approve a suggestion › Headers

Idempotency-Key

string · maxLength: 255

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.

Approve a suggestion › Responses

Success

success

boolean · required

Always true on a successful response.

object · required

The requested record.

POST/suggestions/{id}/approve

curl https://api.mos.getbrokerplus.ca/v1/suggestions/:id/approve \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "object": "suggestion",
    "id": "id",
    "kind": "kind",
    "title": "title",
    "status": "pending",
    "values": {
      "key": "string"
    },
    "approvable": true,
    "deal_id": "deal_id",
    "deal_name": "deal_name",
    "subject_type": "subject_type",
    "subject_id": "subject_id",
    "bundle_key": "bundle_key",
    "bundle_label": "bundle_label",
    "task_id": "task_id",
    "created_by_agent": true,
    "expires_at": "expires_at",
    "dismissed_at": "dismissed_at",
    "dismiss_reason": "dismiss_reason",
    "executed_at": "executed_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Dismiss a suggestion

POST

https://api.mos.getbrokerplus.ca/v1

/suggestions/{id}/dismiss

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.

Dismiss a suggestion › path Parameters

id

string · required

Resource id.

Dismiss a suggestion › Headers

Idempotency-Key

string · maxLength: 255

Dismiss a suggestion › Request Body optional

reason

string · maxLength: 2000

Why you turned it down. The broker sees it.

Dismiss a suggestion › Responses

Success

success

boolean · required

Always true on a successful response.

object · required

The requested record.

POST/suggestions/{id}/dismiss

curl https://api.mos.getbrokerplus.ca/v1/suggestions/:id/dismiss \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "reason": "reason"
}'

Example Request Body

{
  "reason": "reason"
}

json

Example Responses

{
  "success": true,
  "data": {
    "object": "suggestion",
    "id": "id",
    "kind": "kind",
    "title": "title",
    "status": "pending",
    "values": {
      "key": "string"
    },
    "approvable": true,
    "deal_id": "deal_id",
    "deal_name": "deal_name",
    "subject_type": "subject_type",
    "subject_id": "subject_id",
    "bundle_key": "bundle_key",
    "bundle_label": "bundle_label",
    "task_id": "task_id",
    "created_by_agent": true,
    "expires_at": "expires_at",
    "dismissed_at": "dismissed_at",
    "dismiss_reason": "dismiss_reason",
    "executed_at": "executed_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Notes Notifications