Back to top

API Documentation

Deal Inbox

Overview

A Deal Inbox is a brand-scoped queue of deals whose tasks need attention. Each deal lands in an inbox when one of its tasks has attention_requested_at set; the inbox a task belongs to is resolved from its checklist template.

Inboxes are admin-managed: brand administrators create, rename, and delete them, and users subscribe to follow the inboxes they care about.

Root brands are seeded with two default inboxes:

  • Listing Inbox — fallback for Selling-side checklists

  • Contract Inbox — fallback for Offer/Buying-side checklists

Child brands inherit these defaults via the brand-parent walk. They can also define their own inboxes at any level of the hierarchy.

List inboxes for a brand

List inboxes for a brand
GET/brands/:brand/inboxes

Example URI

GET /brands/:brand/inboxes
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "5b91479e-c800-4b1a-8b5f-0859fd79cc28",
      "brand": "8b17c855-9707-4d7b-bf6a-25b49db08935",
      "label": "Contract Inbox",
      "created_by": null,
      "listing_default": false,
      "contract_default": true,
      "created_at": 1792423500.810951,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "c2c7f6b9-b38a-447b-b6df-c74c5a53903e",
      "brand": "ce91e584-91a8-4170-836e-8cd2b352eb47",
      "label": "Custom Inbox",
      "created_by": "ad151564-23e9-4c9d-a6cd-1ee179e901af",
      "listing_default": false,
      "contract_default": false,
      "created_at": 1792423500.909745,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "c148eab8-0316-4a83-90ef-80eea9e940c2",
      "brand": "8b17c855-9707-4d7b-bf6a-25b49db08935",
      "label": "Listing Inbox",
      "created_by": null,
      "listing_default": true,
      "contract_default": false,
      "created_at": 1792423500.810059,
      "deleted_at": null,
      "type": "deal_inbox"
    }
  ],
  "info": {
    "count": 3,
    "total": 0
  }
}

Create an inbox

Create an inbox
POST/brands/:brand/inboxes

Example URI

POST /brands/:brand/inboxes
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
Request
HideShow
Body
{
  "label": "Custom Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "c2c7f6b9-b38a-447b-b6df-c74c5a53903e",
    "brand": "ce91e584-91a8-4170-836e-8cd2b352eb47",
    "label": "Custom Inbox",
    "created_by": "ad151564-23e9-4c9d-a6cd-1ee179e901af",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1792423500.909745,
    "deleted_at": null,
    "type": "deal_inbox"
  }
}

Rename an inbox

Rename an inbox
PATCH/brands/:brand/inboxes/:inbox

Example URI

PATCH /brands/:brand/inboxes/:inbox
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
inbox
string (required) Example: c2c7f6b9-b38a-447b-b6df-c74c5a53903e
Request
HideShow
Body
{
  "label": "Renamed Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "c2c7f6b9-b38a-447b-b6df-c74c5a53903e",
    "brand": "ce91e584-91a8-4170-836e-8cd2b352eb47",
    "label": "Renamed Inbox",
    "created_by": "ad151564-23e9-4c9d-a6cd-1ee179e901af",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1792423500.909745,
    "deleted_at": null,
    "type": "deal_inbox"
  }
}

Delete an inbox

Delete an inbox
DELETE/brands/:brand/inboxes/:inbox

Example URI

DELETE /brands/:brand/inboxes/:inbox
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
inbox
string (required) Example: c2c7f6b9-b38a-447b-b6df-c74c5a53903e
Response  204

Subscribe to an inbox

Subscribe to an inbox
PUT/brands/:brand/inboxes/:inbox/subscription

Example URI

PUT /brands/:brand/inboxes/:inbox/subscription
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
inbox
string (required) Example: c2c7f6b9-b38a-447b-b6df-c74c5a53903e
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "c2c7f6b9-b38a-447b-b6df-c74c5a53903e",
    "brand": "ce91e584-91a8-4170-836e-8cd2b352eb47",
    "label": "Renamed Inbox",
    "created_by": "ad151564-23e9-4c9d-a6cd-1ee179e901af",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1792423500.909745,
    "deleted_at": null,
    "type": "deal_inbox"
  }
}

Unsubscribe from an inbox

Unsubscribe from an inbox
DELETE/brands/:brand/inboxes/:inbox/subscription

Example URI

DELETE /brands/:brand/inboxes/:inbox/subscription
URI Parameters
HideShow
brand
string (required) Example: ce91e584-91a8-4170-836e-8cd2b352eb47
inbox
string (required) Example: c2c7f6b9-b38a-447b-b6df-c74c5a53903e
Response  204

Generated by aglio on 19 Oct 2026