Preview. The endpoints on this page are illustrative and are likely to change as they move toward general availability. Documentation is published in advance so you can start shaping your integration; treat request and response details as subject to revision.

Deal object

A Deal is a pipeline / opportunity record in Cortex — the parent object 8Ps and Q&As hang off. Schema-driven; every deal carries a schemaId pinning the shape of its customFields and a schemaVersion for evolution tracking.

Returned by the endpoints under /api/v1alpha1/deals.

The Deal schema

{
  "id": "deal_...",
  "orgId": "org_...",
  "name": "Acme Q3 Expansion",
  "stage": "Proposal",
  "amount": {
    "value": 125000,
    "currency": "USD"
  },
  "closeDate": "2026-09-30",
  "account": {
    "id": "acct_...",
    "name": "Acme Corporation"
  },
  "owner": {
    "userId": "usr_...",
    "displayName": "Alex Rivera"
  },
  "primaryContact": {
    "id": "cont_...",
    "displayName": "Sample Guest"
  },
  "schemaId": "schm_...",
  "schemaVersion": 3,
  "customFields": {
    "leadSource": "Inbound - Webinar",
    "productLine": "Enterprise",
    "renewalMonths": 12
  },
  "insightSummary": {
    "profileId": "prof_...",
    "problemId": "prob_...",
    "painId": "pain_...",
    "powerId": "powr_...",
    "positionId": "posn_...",
    "phasesId": "phas_...",
    "processId": "proc_...",
    "planId": "plan_..."
  },
  "sourceRefs": {
    "salesforce": {
      "id": "0061U00000abcXYZ",
      "url": "https://acme.my.salesforce.com/0061U00000abcXYZ"
    }
  },
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-07-14T09:30:00Z"
}

Core fields

Field	Type	Description
id	string	Deal id, prefixed deal_.
orgId	string	Your org id, prefixed org_.
name	string	Deal name.
stage	string	Current pipeline stage. Org-configured — the available values come from the schema. Terminal stages Won and Lost make the deal immutable via PATCH.
amount	object	{value, currency}. Currency is always explicit; multi-currency orgs read the deal's own currency. Convert externally for cross-currency reporting.
closeDate	string	(optional) ISO 8601 date.
account	object	{id, name} reference. Required on every deal.
owner	object	{userId, displayName}. The Cirrus user accountable for the deal (from Data.OwnerId), not the org owner.
primaryContact	object	(optional) {id, displayName} reference to the deal's designated primary contact.
createdAt, updatedAt	string	ISO 8601 UTC.

Schema and custom fields

schemaId string

The schema this deal is pinned to, prefixed schm_. Discoverable via the schema catalog (schema management is admin-only in v1alpha1; read-only lookup for partners is a planned follow-up).

schemaVersion number

Version of the schema at the time of the last deal update. When the schema evolves and this deal is subsequently updated, schemaVersion bumps. Lets partners branch on shape changes without breaking on schema migrations.

customFields object

Schema-driven custom-field payload. Keys and value types match the pinned schema.

• Bag of untyped values — top-level shape is polymorphic. A partner integrating deeply against one schema should fetch the schema definition and cache the field shapes. A partner writing generic tooling should treat customFields as opaque.
• Merge semantics on PATCH — updating customFields merges with existing values. To remove a field, pass null.

Insight pointers

insightSummary object

Pointers to the eight 8P records for this deal:

Field	Type	Description
profileId	string	8P Profile, prefixed prof_. null when unpopulated.
problemId	string	Prefixed prob_.
painId	string	Prefixed pain_.
powerId	string	Prefixed powr_.
positionId	string	Prefixed posn_.
phasesId	string	Prefixed phas_.
processId	string	Prefixed proc_.
planId	string	Prefixed plan_.

null on any pointer when the corresponding 8P record hasn't been created yet.

Pointers, not embedded bodies. Fetching every 8P for every deal-detail request would blow up response sizes. The pointer approach lets partners fetch only the 8Ps they care about — walk them one at a time via GET /api/v1alpha1/insights/{id} or all at once via GET /api/v1alpha1/deals/{id}/insights.

External references

sourceRefs object

Same shape as Account.sourceRefs. Map keyed by integration name; each entry {id, url}. The id is the raw external system id (not wrapped in a Platform API prefix).

Setting sourceRefs.salesforce.id on POST /api/v1alpha1/deals also creates an idempotency guard against duplicate deal creation from CRM sync — the record layer rejects a second insert with the same (sourceType, sourceId) pair, surfaced as 422 source-ref-conflict.

Related models

• Account — the company. Every deal has one.
• Contact — the primaryContact reference.
• Insight (8P) record — the eight sub-records that carry the deal's discovery insights.
• Q&A item — questions on the deal.
• Meeting — meetings linked to the deal via GET /api/v1alpha1/deals/{id}/meetings.