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: c0669157-b2e7-4d19-9a82-4448438ed750
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "cc34a590-b226-4139-9c01-d8c7907c8651",
      "brand": "7efaa4b6-1575-4f1e-a129-4a9f486a5f6d",
      "label": "Contract Inbox",
      "created_by": null,
      "listing_default": false,
      "contract_default": true,
      "created_at": 1780325357.842059,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "50776c52-d82b-4faf-85d3-d3315a7c993d",
      "brand": "c0669157-b2e7-4d19-9a82-4448438ed750",
      "label": "Custom Inbox",
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "listing_default": false,
      "contract_default": false,
      "created_at": 1780325358.07517,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "510a64ce-6a1f-4c70-9fd0-7e3d5875c9f5",
      "brand": "7efaa4b6-1575-4f1e-a129-4a9f486a5f6d",
      "label": "Listing Inbox",
      "created_by": null,
      "listing_default": true,
      "contract_default": false,
      "created_at": 1780325357.839102,
      "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: c0669157-b2e7-4d19-9a82-4448438ed750
Request
HideShow
Body
{
  "label": "Custom Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "50776c52-d82b-4faf-85d3-d3315a7c993d",
    "brand": "c0669157-b2e7-4d19-9a82-4448438ed750",
    "label": "Custom Inbox",
    "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1780325358.07517,
    "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: c0669157-b2e7-4d19-9a82-4448438ed750
inbox
string (required) Example: 50776c52-d82b-4faf-85d3-d3315a7c993d
Request
HideShow
Body
{
  "label": "Renamed Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "50776c52-d82b-4faf-85d3-d3315a7c993d",
    "brand": "c0669157-b2e7-4d19-9a82-4448438ed750",
    "label": "Renamed Inbox",
    "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1780325358.07517,
    "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: c0669157-b2e7-4d19-9a82-4448438ed750
inbox
string (required) Example: 50776c52-d82b-4faf-85d3-d3315a7c993d
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: c0669157-b2e7-4d19-9a82-4448438ed750
inbox
string (required) Example: 50776c52-d82b-4faf-85d3-d3315a7c993d
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "50776c52-d82b-4faf-85d3-d3315a7c993d",
    "brand": "c0669157-b2e7-4d19-9a82-4448438ed750",
    "label": "Renamed Inbox",
    "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1780325358.07517,
    "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: c0669157-b2e7-4d19-9a82-4448438ed750
inbox
string (required) Example: 50776c52-d82b-4faf-85d3-d3315a7c993d
Response  204

Generated by aglio on 01 Jun 2026