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: c4beaa39-e38a-4591-96b2-e0c591b89e98
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "9908308b-e306-420e-abfc-60e76ad573af",
      "brand": "abbf0631-9a5f-437c-a645-23a3797e6e1d",
      "label": "Contract Inbox",
      "created_by": null,
      "listing_default": false,
      "contract_default": true,
      "created_at": 1788495061.116526,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "5dfcd467-113f-4d32-a5e1-dafdf1f59731",
      "brand": "c4beaa39-e38a-4591-96b2-e0c591b89e98",
      "label": "Custom Inbox",
      "created_by": "e1cd6ff1-231a-4a0e-81e8-779a9e8118c3",
      "listing_default": false,
      "contract_default": false,
      "created_at": 1788495061.302273,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "c2b01025-f41d-4335-b701-225f7f7db989",
      "brand": "abbf0631-9a5f-437c-a645-23a3797e6e1d",
      "label": "Listing Inbox",
      "created_by": null,
      "listing_default": true,
      "contract_default": false,
      "created_at": 1788495061.111991,
      "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: c4beaa39-e38a-4591-96b2-e0c591b89e98
Request
HideShow
Body
{
  "label": "Custom Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "5dfcd467-113f-4d32-a5e1-dafdf1f59731",
    "brand": "c4beaa39-e38a-4591-96b2-e0c591b89e98",
    "label": "Custom Inbox",
    "created_by": "e1cd6ff1-231a-4a0e-81e8-779a9e8118c3",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1788495061.302273,
    "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: c4beaa39-e38a-4591-96b2-e0c591b89e98
inbox
string (required) Example: 5dfcd467-113f-4d32-a5e1-dafdf1f59731
Request
HideShow
Body
{
  "label": "Renamed Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "5dfcd467-113f-4d32-a5e1-dafdf1f59731",
    "brand": "c4beaa39-e38a-4591-96b2-e0c591b89e98",
    "label": "Renamed Inbox",
    "created_by": "e1cd6ff1-231a-4a0e-81e8-779a9e8118c3",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1788495061.302273,
    "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: c4beaa39-e38a-4591-96b2-e0c591b89e98
inbox
string (required) Example: 5dfcd467-113f-4d32-a5e1-dafdf1f59731
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: c4beaa39-e38a-4591-96b2-e0c591b89e98
inbox
string (required) Example: 5dfcd467-113f-4d32-a5e1-dafdf1f59731
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "5dfcd467-113f-4d32-a5e1-dafdf1f59731",
    "brand": "c4beaa39-e38a-4591-96b2-e0c591b89e98",
    "label": "Renamed Inbox",
    "created_by": "e1cd6ff1-231a-4a0e-81e8-779a9e8118c3",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1788495061.302273,
    "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: c4beaa39-e38a-4591-96b2-e0c591b89e98
inbox
string (required) Example: 5dfcd467-113f-4d32-a5e1-dafdf1f59731
Response  204

Generated by aglio on 04 Sep 2026