Handle Company Compare To

​

CRM-9823 — Δ and Impact for one page of the Companies table.

The company-grain counterpart to /compare. Same shape, same timeframe vocabulary, and the same reason for being a separate endpoint rather than an extension of POST /filter: these values are computed per request from two points in time, and that router sorts and filters over real columns on the queried model.

Four metrics, not twelve. companies carries no CARR/CMRR and no _local pair, so there is no terms-currency twin to return.

A company deleted between the page load and this call is reported in notFoundCompanyIds rather than omitted. The contract-grain endpoint drops such ids, which makes a page of deleted rows indistinguishable from a page where nothing moved — that is the one behaviour this endpoint deliberately does not copy.

Body·

required
application/json

A Compare to request for one page of the Companies table (CRM-9823).

Row ids come from the caller for the reason the contract-grain request does: 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, which keeps this out of the shared /filter router — that one filters and sorts over real columns, and these values are computed per request from two points in time.

  • companyIds
    Type: array of string 1…200
    required

    Company 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/companies/compare
curl https://crm.dreamhub.ai/api/v1/contracts/companies/compare \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "companyIds": [
    ""
  ],
  "period": "last30Days",
  "customStart": ""
}'

{
  "period": "string",
  "periodStart": "2026-10-07T22:43:40.393Z",
  "companies": [
    {
      "companyId": "string",
      "existed": true,
      "previousCapturedAt": "2026-10-07T22:43:40.393Z",
      "previousSource": "string",
      "metrics": {
        "additionalProperty": {
          "previous": 1,
          "current": 1,
          "delta": 1,
          "impact": "new"
        }
      }
    }
  ],
  "notFoundCompanyIds": [
    "string"
  ]
}

Successful Response