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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "3a443d26-9d58-4b2f-a543-9b1fe8d482a0",
      "brand": "7d5d3554-9cd9-4f49-acfc-92466377a7bc",
      "label": "Contract Inbox",
      "created_by": null,
      "listing_default": false,
      "contract_default": true,
      "created_at": 1784555791.260876,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "91d4079e-c2dd-4fc6-b004-64e0b899a2e2",
      "brand": "542e96dc-4ba0-4770-931b-bfe47c18fcd6",
      "label": "Custom Inbox",
      "created_by": "222478fa-9bca-462c-9773-08748530999d",
      "listing_default": false,
      "contract_default": false,
      "created_at": 1784555791.436519,
      "deleted_at": null,
      "type": "deal_inbox"
    },
    {
      "id": "937d54b8-ffc0-4d97-a218-86636372d96d",
      "brand": "7d5d3554-9cd9-4f49-acfc-92466377a7bc",
      "label": "Listing Inbox",
      "created_by": null,
      "listing_default": true,
      "contract_default": false,
      "created_at": 1784555791.258599,
      "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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
Request
HideShow
Body
{
  "label": "Custom Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "91d4079e-c2dd-4fc6-b004-64e0b899a2e2",
    "brand": "542e96dc-4ba0-4770-931b-bfe47c18fcd6",
    "label": "Custom Inbox",
    "created_by": "222478fa-9bca-462c-9773-08748530999d",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1784555791.436519,
    "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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
inbox
string (required) Example: 91d4079e-c2dd-4fc6-b004-64e0b899a2e2
Request
HideShow
Body
{
  "label": "Renamed Inbox"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "91d4079e-c2dd-4fc6-b004-64e0b899a2e2",
    "brand": "542e96dc-4ba0-4770-931b-bfe47c18fcd6",
    "label": "Renamed Inbox",
    "created_by": "222478fa-9bca-462c-9773-08748530999d",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1784555791.436519,
    "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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
inbox
string (required) Example: 91d4079e-c2dd-4fc6-b004-64e0b899a2e2
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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
inbox
string (required) Example: 91d4079e-c2dd-4fc6-b004-64e0b899a2e2
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "91d4079e-c2dd-4fc6-b004-64e0b899a2e2",
    "brand": "542e96dc-4ba0-4770-931b-bfe47c18fcd6",
    "label": "Renamed Inbox",
    "created_by": "222478fa-9bca-462c-9773-08748530999d",
    "listing_default": false,
    "contract_default": false,
    "created_at": 1784555791.436519,
    "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: 542e96dc-4ba0-4770-931b-bfe47c18fcd6
inbox
string (required) Example: 91d4079e-c2dd-4fc6-b004-64e0b899a2e2
Response  204

Generated by aglio on 20 Jul 2026