Policies

Overview

The /api/Policies collection support day-two transactions on policies (ie, everything that happens after a policy is initially created). This includes managing proposal workflow states, creating endorsements for cancellations and reinstatements, adjusting billing, and recording payments.

All endpoints use POST, including the two lookup endpoints that are semantically read-only.

Example Use Cases

Proposal Workflow

These endpoints transition a proposal through its lifecycle states. Each accepts a proposalID in the route and optional comments as a query parameter.

Endpoint	Route	Purpose
Accept	`POST {proposalID}/Accept`	Mark a proposal as accepted
UndoAccept	`POST {proposalID}/UndoAccept`	Reverse an acceptance
Reject	`POST {proposalID}/Reject`	Mark a proposal as rejected
UndoReject	`POST {proposalID}/UndoReject`	Reverse a rejection
UndoBinding	`POST {proposalID}/UndoBinding`	Reverse a binding

                  ┌──────────┐
                  │ Proposed │
                  └────┬─────┘
                       │
            ┌──────────┼──────────┐
            ▼                     ▼
      ┌──────────┐          ┌──────────┐
      │ Accepted │          │ Rejected │
      └────┬─────┘          └────┬─────┘
           │                     │
      UndoAccept            UndoReject
           │                     │
           ▼                     ▼
      ┌──────────┐          ┌──────────┐
      │ Proposed*│          │ Proposed*│
      └────┬─────┘          └──────────┘
           │
           ▼
      ┌──────────┐
      │  Bound   │
      └────┬─────┘
           │
      UndoBinding
           │
           ▼
      ┌──────────┐
      │ Proposed*│
      └──────────┘
      

* When "SetProposalStatustoPreAcceptOrRejectAfterUndo" is enabled, undo operations restore the proposal to its status before the accept or reject, rather than always reverting to "Proposed."

Policy Lifecycle

These endpoints create endorsement proposals that modify an existing policy. Each accepts a policyID in the route.

Endpoint	Route	Purpose
Endorse	`POST {policyID}/Endorse`	Create a general endorsement
Cancel	`POST {policyID}/Cancel`	Create a cancellation endorsement
Reinstate	`POST {policyID}/Reinstate`	Create a reinstatement endorsement

Cancel and Reinstate both accept a JSON request body with PolicyTransaction fields (reason codes, descriptions, custom fields, etc.). See the individual endpoint docs for the full list of supported fields.

Billing

Endpoint	Route	Purpose
ChangeBillingFrequency	`POST {policyID}/ChangeBillingFrequency`	Change how often invoices are generated
MakePayment	`POST {policyID}/MakePayment`	Record a payment and allocate it against outstanding invoices

Lookup

These endpoints return reference data used by other Policies endpoints. Both use POST but are semantically read-only — they do not modify any data.

Endpoint	Route	Purpose
CancellationReasonCodes	`POST Codes/CancellationReasonCodes`	List valid cancellation reason codes for a policy
ReinstatementReasonCodes	`POST Codes/ReinstatementReasonCodes`	List valid reinstatement reason codes