generated: '2026-07-25'
method: derived
source: openapi/whitespace-london-platform-openapi.yml
docs:
- https://apidocs.whitespace.co.uk/Whitespace_Contract_Data_Persistence.pdf
- https://apidocs.whitespace.co.uk/Risk_Stages.pdf
- https://apidocs.whitespace.co.uk/Whitespace_Data_Dictionary.xlsx
- https://apidocs.whitespace.co.uk/Integrating_with_Whitespace_via_Queues_3.1.pdf
summary: >-
  Whitespace is a document store, not a relational API. Everything is a JSON platform document
  in Couchbase with a compound string _id, a _rev, a type discriminator (the RW* family), and a
  channels[] array that carries authorisation. There are no numeric foreign keys: relationships
  are expressed by embedding one document's _id inside another (parentDocID, associatedRootID,
  associatedPlacingID, endorsementDocID, linkedArchiveID) and, above all, by the ID itself —
  every document under a slip begins with that slip's 38-character root ID.
id_grammar:
  root: 'IC + 36 characters — the root risk (the whole slip, all stages and instances)'
  instance: '<rootID>::<STAGE> — a specific contract instance, e.g. <rootID>::FO'
  child: '<rootID>::<STAGE>::<TYPECODE>::<uuid> — a document under that instance'
  user: 'MU + 36 characters — permanent per corporate identity'
  separator: '::'
  known_segments:
  - code: FO
    meaning: Firm Order stage instance
  - code: ACTI
    meaning: Activity document
  - code: ARCH
    meaning: Archive document
  - code: ATCH
    meaning: Attachment document
  - code: LGUS
    meaning: Line guidance set
  note: >-
    Endpoints taking {rootID} accept only the root form; endpoints taking {riskID} or {docID}
    accept the full instance/child form. See conventions/whitespace-london-conventions.yml.
common_fields:
  _id: compound document identifier
  _rev: 'Couchbase revision, "<n>-<hash>"; must be current on write (optimistic concurrency)'
  type: document type discriminator (the RW* name)
  channels: array of companyid_TEAMID strings controlling visibility
  createdAt / updatedAt: '"YYYY-MM-DD HH:MM:SS" timestamps'
  provenance: '{dataHash, provHash, system, userID, version, writtenAt} write audit block'
entities:
- name: Risk (slip / RWPlacing)
  schema: RWPlacing
  id: rootID (IC...)
  description: >-
    The contract itself, carrying the MRCContract body plus control metadata. A risk moves
    through stages (draft, quote, bindable quote, firm order, signed, endorsement) and each
    stage is a separate instance document under the same root.
  operations:
  - GET /api/risks/{riskID}
  - POST /api/risks/save
  - POST /api/risks/newDraft
  - GET /api/risks/root/{rootID}
  - GET /api/risks/{rootID}/related/{type}
- name: ExtendedMRC
  schema: ExtendedMRC
  description: >-
    The enriched read model of a risk — MRCContract plus questionnaire, written and signed line
    sets, proposed endorsement followers, platform references and provenance.
  operations:
  - GET /api/risks/{riskID}/getExtendedMRC
- name: Activity
  schema: RWActivity
  id: <rootID>::<STAGE>::ACTI::<uuid>
  description: >-
    The append-only history record generated by every significant platform action; also the unit
    placed on the client's Azure Service Bus queue.
  operations:
  - GET /api/activities/{riskID}
  - GET /api/activities/{rootID}/full
  - POST /api/activities/filter
  - GET /api/activities/filter/help
- name: WrittenLineSet
  schema: RWWrittenLineSet
  description: An underwriter's committed participation on a contract instance.
  operations:
  - POST /api/risks/{riskID}/writeLine
  - POST /api/risks/{riskID}/requestWrittenLineSets
  - POST /api/risks/{riskID}/acceptWrittenLine/{writtenLineSetID}
  - POST /api/risks/{riskID}/rejectWrittenLine/{writtenLineSetID}
  - GET /api/lines/{rootID}/combinedSets
- name: SignedLineSet
  schema: RWSignedLineSet
  description: The signed-down participation set after the broker signs the contract.
  operations:
  - POST /api/risks/{riskID}/signSets
  - POST /api/risks/{riskID}/reSignSets
  - POST /api/risks/{riskID}/rollbackSigned
- name: QuotedLine
  schema: RWQuotedLine
  operations:
  - POST /api/risks/{riskID}/quoteOnRequest
  - POST /api/risks/{riskID}/saveQuoteDetails
  - GET /api/risks/{riskID}/getQuoteDetails
- name: LineGuidanceSet
  schema: RWLineGuidanceSet
  description: Broker guidance on acceptable written-line percentages for a placing.
  operations:
  - GET /api/documents/getLineGuidanceForRoot/{rootID}
- name: BindableQuoteGuidance
  schema: RWBindableQuoteGuidance
  operations:
  - POST /api/risks/{riskID}/createBindableQuote
- name: FacilityGuidance
  schema: RWFacilityGuidance
  operations:
  - POST /api/declarations/{riskID}/showToFacility/{facilityID}
  - POST /api/bindNotifyParties
- name: QuotedFacilityGuidance
  schema: RWQuotedFacilityGuidance
- name: EndorsementFollower
  schema: RWEndorsementFollower
  operations:
  - GET /api/endorsements/{rootID}
  - GET /api/risks/{riskID}/endorsementFollowers
  - POST /api/risks/{riskID}/setEndorsementFollowerRoles
  - POST /api/risks/{riskID}/setEndorsementFollowerTemplate
  - POST /api/risks/{riskID}/completeEndorsement
- name: SubjectivityResponse
  schema: RWSubjectivityResponse
  description: A broker's response to an underwriter's condition of cover.
- name: NoCoverGivenLinesStorer
  schema: RWNoCoverGivenLinesStorer
- name: CorrectionDetails
  schema: RWCorrectionDetails
  operations:
  - POST /api/risks/{riskID}/createContractCorrection
- name: RiskAuthorisationState
  schema: RWRiskAuthorisationState
  description: Internal-review / second-approval state for a contract.
  operations:
  - POST /api/risks/{riskID}/selfApproveSecondApproval
- name: MRCValidationResults
  schema: RWMRCValidationResults
  description: Rule-based validation narrative for a contract against MRC expectations.
- name: RiskSummary
  schema: RWRiskSummary
  operations:
  - GET /api/summary
  - POST /api/summary
  - GET /api/summary/pinned
- name: AttachmentCollection
  schema: RWAttachmentCollection
  operations:
  - GET /api/attachments/{rootID}
  - GET /api/attachments/array/{rootID}
  - GET /api/attachments/{parentDocID}/{identifier}
  - POST /api/attachments/{riskID}/{attachmentName}
  - POST /api/attachments/{rootID}/showToCarriers
  - POST /api/attachbyunderwriter/{riskID}/{underwriter_channel}/{attachmentname}
- name: Comment
  schema: RWComment
  operations:
  - POST /api/comments
  - GET /api/comments/global
  - GET /api/risks/{rootID}/related/{type}
- name: BrokerMessage
  schema: RWBrokerMessage
- name: Label
  schema: RWLabel
  operations:
  - GET /api/labels/{root_or_label_ID}
  - POST /api/labels/{root_or_label_ID}
  - DELETE /api/labels/{root_or_label_ID}
  - GET /api/labels/suggested
  - GET /api/labels/teamLabels
- name: AttentionWanted
  schema: RWAttentionWanted
  description: A flag raised for a recipient role that something needs their attention.
- name: MultiSectionStorer
  schema: RWMultiSectionStorer
  operations:
  - POST /api/sections/{rootID}/save
- name: DefinedData
  schema: DefinedData
  description: >-
    The structured contract values — metadata, multiSectionDefinition, contract headings and the
    tagged definedData payload, addressable by MRC heading or by an alternative tagset (ACORDGPM).
  operations:
  - GET /api/v23.09/data/{riskID}
  - POST /api/v23.09/data/{riskID}
  - GET /api/v23.09/data/{riskID}/tagset/{tagset}
  - POST /api/v23.09/data/{riskID}/verify
- name: CorporateDetail
  schema: CorporateDetail
  id: companyId
  description: >-
    An organisation on the platform with its teams, members, admins, permissions, stamps,
    authority details and channels.
  operations:
  - GET /api/shared/corporate
  - GET /api/shared/compressedCorporate
  - GET /api/shared/corporate/memberStates
- name: ApprovedCarrierList
  schema: ApprovedCarrierList
  operations:
  - GET /api/documents/corporateApprovedCarriers/getAll
  - POST /api/documents/corporateApprovedCarriers/saveAndPropagate
- name: User
  id: MU...
  operations:
  - GET /api/user/myDetails
  - GET /api/user/colleagues
  - GET /api/user/colleagues/{state}
  - GET /api/lookup/person/{email}
relationships:
- from: Risk
  to: Activity
  cardinality: has_many
  via: parentDocID (and the shared root prefix of _id)
- from: Activity
  to: Risk
  cardinality: belongs_to
  via: parentDocID / linkedArchiveID / apnsData.subscriptionRootID
- from: Risk
  to: WrittenLineSet
  cardinality: has_many
  via: parentDocID
- from: Risk
  to: SignedLineSet
  cardinality: has_many
  via: parentDocID
- from: ExtendedMRC
  to: WrittenLineSet
  cardinality: has_many
  via: writtenLineSets
- from: ExtendedMRC
  to: SignedLineSet
  cardinality: has_many
  via: signedLineSets
- from: LineGuidanceSet
  to: Risk
  cardinality: belongs_to
  via: associatedPlacingID
- from: BindableQuoteGuidance
  to: Risk
  cardinality: belongs_to
  via: associatedPlacingID
- from: Comment
  to: Risk
  cardinality: belongs_to
  via: associatedRootID
- from: Comment
  to: BrokerMessage
  cardinality: has_one
  via: brokerMessageDocID
- from: BrokerMessage
  to: Risk
  cardinality: belongs_to
  via: associatedRiskID
- from: MultiSectionStorer
  to: Risk
  cardinality: belongs_to
  via: associatedRootID
- from: Label
  to: Risk
  cardinality: belongs_to
  via: rootID
- from: AttentionWanted
  to: Risk
  cardinality: belongs_to
  via: associatedRiskID / associatedRootID
- from: SubjectivityResponse
  to: Risk
  cardinality: belongs_to
  via: associatedFirmOrderDocID / associatedSetDocID / associatedAwDocID
- from: NoCoverGivenLinesStorer
  to: Risk
  cardinality: belongs_to
  via: associatedFirmOrderDocID
- from: EndorsementFollower
  to: Risk
  cardinality: belongs_to
  via: endorsementDocID
- from: CorrectionDetails
  to: Risk
  cardinality: belongs_to
  via: parentDocID
- from: RiskSummary
  to: Risk
  cardinality: belongs_to
  via: rootID
- from: CorporateDetail
  to: User
  cardinality: has_many
  via: members[].uniqueID
- from: Label
  to: CorporateDetail
  cardinality: belongs_to
  via: companyID / teamID
- from: 'Every document'
  to: Channel
  cardinality: has_many
  via: channels[]
  note: Authorisation edge — a caller sees a document only if it carries one of their channels.
stages:
  source: https://apidocs.whitespace.co.uk/Risk_Stages.pdf
  observed_in_ids:
  - FO (Firm Order)
  narrative: >-
    The placing lifecycle runs draft -> quote request -> quote (or bindable quote) -> firm order
    -> written lines -> signed -> endorsement, each stage materialising a new instance document
    under the same root ID so no prior state is overwritten.
render: null