Cancel Policy Endorsement

Time	Status	User Agent
Retrieving recent requests…

Overview

Creates a cancellation endorsement for a bound policy. This does not immediately cancel the policy — it creates an endorsement proposal representing the cancellation, applies the cancellation as a policy change, and rates the endorsement. The returned RecordID is the new endorsement's ProposalID.

What this endpoint does:

Loads the policy by policyID
Validates the policy can be cancelled (not already cancelled, not a book policy, cancel date not past expiry)
Creates a PolicyChange record with action Delete and type Cancellation
Populates the policy transaction from the request body (cancellation reason, description, etc.)
Creates a cancellation endorsement proposal via CreateEndorsement
Accepts the policy change against the endorsement and rates it
Returns the new endorsement's ProposalID

The request body is a JSON representation of the PolicyTransaction dataDictionary.

See the API reference for api/MetaData/Domains/{domain}/DataDictionary where PolicyTransaction is the {domain} value.

If a key is unrecognized, the API throws InvalidOperationException("Unknown field: {key}").

The supplied fields are applied to a new PolicyTransaction object, then copied onto the cancellation's policy transaction record. The following system-managed fields are excluded from the copy (they are set automatically):

Excluded field	Reason
`PolicyTransactionID`	Auto-generated primary key
`ClientID`	Set from the policy
`MemberID`	Set from the policy
`MemberTransactionID`	Set by the system
`Type`	Always set to `Cancellation`
`PolicyID`	Set from the policy
`ProposalID`	Set from the endorsement
`EntryDate`	Set to current timestamp
`EntryUserID`	Set to the authenticated user
`TransactionDate`	Set to the `cancelDate` parameter
`CancellationType`	Derived from `IsFlatCancellation` / `IsShortRateCancellation`

Cancellation-Specific Fields

These are the fields most commonly used for cancellations:

Field	Type	Description
`CancellationReasonID`	int	ID of the cancellation reason code. Use the `Codes/CancellationReasonCodes` endpoint to retrieve valid values for a given policy.
`Description`	string (max 250)	Notes or description for the cancellation transaction
`CancelledBy`	string (1 char)	Code indicating who initiated the cancellation (e.g., insurer, insured)
`IsFlatCancellation`	bool	Flat cancellation — full premium returned regardless of time elapsed
`IsShortRateCancellation`	bool	Short-rate cancellation — premium returned with a penalty factor

IsFlatCancellation and IsShortRateCancellation are mutually exclusive. If both are set, flat takes priority. If neither is set, the cancellation uses pro-rata calculation (default).

Other Supported Fields

Any writable PolicyTransaction field can be included in the request body. Beyond the cancellation-specific fields above, commonly available fields include:

Field	Type	Description
`Amount`	decimal	Transaction amount
`Source`	string (max 250)	Source identifier for the transaction
`CoverageID`	int	Link to a specific coverage
`PremiumCategoryID`	int	Premium category for the transaction
`CustomText1` – `CustomText10`	string (max 256)	Custom text fields
`CustomDate1` – `CustomDate5`	DateTime	Custom date fields
`CustomBool1` – `CustomBool5`	bool	Custom boolean fields
`CustomNumber1` – `CustomNumber5`	decimal	Custom numeric fields
`CustomMoney1` – `CustomMoney5`	decimal	Custom currency fields
`CustomCode1ID` – `CustomCode10ID`	int	Custom code list lookups
`CustomUser1ID` – `CustomUser5ID`	int	Custom user reference fields
`CustomNarrative1` – `CustomNarrative5`	string	Custom long-text fields
`CustomMultiSelectCode1` – `CustomMultiSelectCode5`	string	Custom multi-select code values

Note: The actual field names available depend on your schema's PolicyTransaction domain configuration. Custom fields may have display name overrides — use the field's internal name (as shown above), not the display label.

Example Requests

POST /api/Policies/12345/Cancel?cancelDate=2026-06-01
Content-Type: application/json

{
  "CancellationReasonID": 42,
  "Description": "Insured requested cancellation"
}

POST /api/Policies/12345/Cancel?cancelDate=2026-06-01
Content-Type: application/json

{
  "IsFlatCancellation": true,
  "CancellationReasonID": 7
}

Minimal request (no policy transaction data):

POST /api/Policies/12345/Cancel?cancelDate=2026-06-01
Content-Type: application/json

null

Overview

Cancellation-Specific Fields

Other Supported Fields

Example Requests

200