Handle Compare To

​

CRM-9612 — Δ and Impact for one page of the Contracts table.

Read-only companion to the table's own paginated read: the client sends the row ids it already holds and gets back the movement over the selected timeframe. It is a separate endpoint rather than an extension of POST /filter because that router filters and sorts over real columns on the queried model, and these values are computed per request from two points in time. The consequence is that the Δ columns cannot be server-sorted — the tables already support unsortable columns for exactly this case.

A contract deleted between the page load and this call is omitted rather than reported as empty. A contract with no recorded financials at or before the period start is returned with existed=False: that is a fact about the contract, and CRM-9606's Impact rules distinguish it from having been worth nothing.

Body·

required
application/json

A Compare to request for one page of the Contracts table (CRM-9612).

Row ids come from the caller because the comparison is a companion to the table's own paginated read, not a replacement for it: the client already holds the page and asks only for the movement on those rows. That keeps this endpoint out of the shared /filter router, which cannot express a request-scoped computed column.

  • contractIds
    Type: array of string 1…200
    required

    Contract IDs to compare, normally the current page. Capped so one request cannot fan out across a whole tenant.

  • period
    Type: stringenum
    required

    Comparison timeframe. MTD, QTD and YTD follow the account's fiscal calendar; last30Days and last12Months are counted back from today.

    values
    last30Daysmtdqtdytdlast12Monthscustom
  • customStart
    Type: stringFormat: datenullable

    Start date, required when period is 'custom' and ignored otherwise

Responses

  • application/json
  • application/json
Request Example for post/compare
curl https://crm.dreamhub.ai/api/v1/contracts/compare \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "contractIds": [
    ""
  ],
  "period": "last30Days",
  "customStart": ""
}'

{
  "period": "string",
  "periodStart": "2026-10-07T22:43:40.394Z",
  "contracts": [
    {
      "contractId": "string",
      "existed": true,
      "previousCapturedAt": "2026-10-07T22:43:40.394Z",
      "currency": "string",
      "previousCurrency": "string",
      "metrics": {
        "additionalProperty": {
          "previous": 1,
          "current": 1,
          "delta": 1,
          "impact": "new"
        }
      }
    }
  ]
}

Successful Response