Update proposals

Update proposals

A proposal is a “the source of something you hold has a newer version” notice: the person — or, for a company’s record, whoever edits inside that company — published a new version of a resource your organization holds a copy of, and the request now asks you to decide. On an auto slot the new version is kept without a decision (queued while your key is cold); on a manual slot it becomes a proposal. Every route here needs request_manage.

List the open proposals

GET /org/v1/requests/{requestId}/proposals

{
  "proposals": [
    {
      "proposalId": "a1b2…",
      "slotId": "7c2b9e11-30cf-4f2e-9f57-b8a4f7f4f2ad",
      "itemKind": "schema",
      "itemTarget": "PersonBankAccount",
      "resourceId": "b7d0…",
      "newVersion": 5,
      "proposedAt": "2026-09-10T08:00:00Z",
      "participant": null
    }
  ]
}

• One notice per granted resource at most, superseded in place by later edits — newVersion is always the newest. Address a decision by the notice’s own proposalId.
• A proposal carries no diff. Comparing against the copy you already keep (its currentData on /copies) is the reader’s own work.
• participant names the party, never the typist. A notice about a company’s record is raised by whoever edited it inside that company — any collaborator with write access — and reaches this request because the recipient may still answer for that company; null means the recipient’s own record.
• Notices are not a complete audit of the source. An edit made while the recipient could not answer for that party (they had lost the Manager role, say) raises none, and regaining the role does not replay it: the live reads — the request’s records and the partner plane — show the current version, but no notice appears for the edit that was missed.

Preview the proposed version

GET /org/v1/requests/{requestId}/proposals/{proposalId}/candidate

The content of the version the person produced, read from their vault in the member’s key context. Looking is taking: this writes a read receipt on the person’s side, attributed to your app. Decide from the request detail’s sourceVersion where you can, and preview when the values matter.

{
  "proposal": { "proposalId": "a1b2…", "newVersion": 5, "…": "…" },
  "version": 5,
  "name": "Payout account",
  "schemaRef": "https://schema.identa.io/core/PersonBankAccount.json",
  "data": { "bankName": "Nya Banken", "accountNumber": "SE45…", "currency": "SEK" }
}

Keep the proposed version

POST /org/v1/requests/{requestId}/proposals/{proposalId}/adopt

Keeps the proposed version as your organization’s copy — the next version of that record’s chain — and closes the proposal. A notice is about one granted resource, so this keeps one copy; on a slot answered by several resources the other notices are decided on their own. Answers the Adoption produced; a cold key answers 423 org_sealed.

Dismiss it

POST /org/v1/requests/{requestId}/proposals/{proposalId}/dismiss

Closes the proposal without keeping the version; your copy stays as it was. A later edit opens a fresh proposal.

{ "dismissed": true }

dismissed: false means there was no open proposal under that id any more — another member decided it, or a newer edit superseded it in place.