{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/capepartners-fr/json-schema/capepartners-fr-deal-flow-response-schema.json",
  "title": "DealFlowResponse",
  "description": "The supply-side counterpart of the Interest Signals card: the counterparty universe that matches the session's OWN mandate, ranked, with what is new and the session's watchlist. Names are masked (\"Company A\") until the session's agreement is confirmed — the same reveal rule as /api/matches — so the payload is safe to render pre-reveal. Shares ONE memoised universe sweep with GET /api/interest-signals (24h TTL per entity).",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/capepartners-fr-dealflow-api-openapi.yml#/components/schemas/DealFlowResponse",
  "type": "object",
  "properties": {
    "context": {
      "type": "string",
      "enum": [
        "seller",
        "buyer"
      ],
      "description": "Which side this session owns."
    },
    "counterparty_type": {
      "type": "string",
      "enum": [
        "seller",
        "buyer"
      ],
      "description": "The side being described (the opposite of context)."
    },
    "entity_id": {
      "type": "integer"
    },
    "entity_name": {
      "type": "string"
    },
    "names_revealed": {
      "type": "boolean",
      "description": "True only when the session's ToS/NDA signature is confirmed. When false every name is \"Company <letter>\"."
    },
    "mandate": {
      "type": "object",
      "description": "The session's own criteria, echoed back (buyers: ticket range, geography, growth/EBITDA targets, sector; sellers: revenue, growth, valuation, sector)."
    },
    "universe": {
      "type": "object",
      "properties": {
        "matched": {
          "type": "integer",
          "description": "Counterparties at or above the fit threshold (50)."
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Counterparties swept (denominator)."
        },
        "threshold": {
          "type": [
            "number",
            "null"
          ]
        },
        "best_score": {
          "type": [
            "number",
            "null"
          ]
        },
        "median_score": {
          "type": [
            "number",
            "null"
          ]
        },
        "bands": {
          "type": "object",
          "description": "Score-band distribution of the matched set (50-55 / 55-60 / 60-65 / 65+).",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "sectors": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "sector": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "avg_data_quality": {
          "type": [
            "number",
            "null"
          ]
        },
        "scored": {
          "type": [
            "integer",
            "null"
          ]
        },
        "unscored": {
          "type": [
            "integer",
            "null"
          ]
        },
        "computed_at": {
          "type": [
            "number",
            "null"
          ]
        },
        "cached": {
          "type": "boolean"
        },
        "truncated": {
          "type": "boolean",
          "description": "True when the ranked list was capped."
        }
      }
    },
    "fresh": {
      "type": "object",
      "description": "Freshness over the matched set. A counterparty's \"last touch\" is the later of its own record timestamp and its newest enrichment/update event; most sellers have no created_at, so the event is the signal.",
      "properties": {
        "window_days": {
          "type": "integer"
        },
        "counts": {
          "type": "object",
          "description": "Matched counterparties touched within 7 / 30 / 90 days.",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "count": {
          "type": "integer"
        },
        "items": {
          "type": "array",
          "description": "Newest touches first (capped at 12).",
          "items": {
            "$ref": "#/$defs/DealFlowCounterparty"
          }
        }
      }
    },
    "top": {
      "type": "array",
      "description": "The ranked fits (capped at 25).",
      "items": {
        "$ref": "#/$defs/DealFlowCounterparty"
      }
    },
    "watchlist": {
      "type": "array",
      "description": "Counterparties this session pinned, with their current fit, data quality and pairing phase.",
      "items": {
        "type": "object",
        "properties": {
          "entity_type": {
            "type": "string",
            "enum": [
              "seller",
              "buyer"
            ]
          },
          "entity_id": {
            "type": "integer"
          },
          "note": {
            "type": "string"
          },
          "watched_at": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null until the agreement is confirmed."
          },
          "score": {
            "type": [
              "number",
              "null"
            ]
          },
          "data_quality": {
            "type": [
              "integer",
              "null"
            ]
          },
          "phase": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "$defs": {
    "DealFlowCounterparty": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "type": {
          "type": "string",
          "enum": [
            "seller",
            "buyer"
          ]
        },
        "name": {
          "type": "string",
          "description": "Real name when names_revealed, else \"Company <letter>\"."
        },
        "revealed": {
          "type": "boolean"
        },
        "score": {
          "type": "number",
          "description": "Canonical fit score (deterministic x semantic)."
        },
        "sector": {
          "type": "string"
        },
        "data_quality": {
          "type": "number"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_touch": {
          "type": [
            "string",
            "null"
          ],
          "description": "Null when the counterparty has neither a record timestamp nor any logged event — reported as unknown, never invented."
        },
        "touch_kind": {
          "type": "string",
          "enum": [
            "sourced",
            "enriched"
          ]
        },
        "paired_phase": {
          "type": [
            "string",
            "null"
          ],
          "description": "Phase of this pairing for the session, when one exists."
        },
        "watched": {
          "type": "boolean"
        },
        "has_session": {
          "type": "boolean"
        },
        "revenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "Seller counterparties only."
        },
        "growth": {
          "type": [
            "number",
            "null"
          ],
          "description": "Seller counterparties only (fraction)."
        },
        "ebitda_margin": {
          "type": [
            "number",
            "null"
          ]
        },
        "valuation": {
          "type": [
            "number",
            "null"
          ]
        },
        "geography": {
          "type": "string"
        },
        "ticket_min": {
          "type": [
            "number",
            "null"
          ],
          "description": "Buyer counterparties only."
        },
        "ticket_max": {
          "type": [
            "number",
            "null"
          ]
        },
        "growth_target": {
          "type": [
            "number",
            "null"
          ]
        },
        "ebitda_target": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    }
  }
}