Policy API

Endpoint Index

ActionEndpoint
Create a policyPOST /policy
Fetch a policyGET /policy/{policyLocator}
Update a draft policyPOST /policy/{policyLocator}/update
Finalize a policyPOST /policy/{policyLocator}/finalize
Issue a policyPOST /policy/{policyLocator}/issue
Discard a policyPOST /policy/{policyLocator}/discard
Add a document to a policyPOST /policy/{policyLocator}/addDocument
Remove a document from a policyPOST /policy/{policyLocator}/removeDocument
Fetch a policy's automated underwriting resultGET /policy/{policyLocator}/automatedUnderwritingResult
Add or reverse feesPATCH /policy/{policyLocator}/fees
Fetch a policy's pricing dataGET /policy/{policyLocator}/price
Price a policyPOST /policy/{policyLocator}/price
Change Payment SchedulePOST /policy/{policyLocator}/paymentSchedule
Fetch a policy's invoicesGET /policy/{policyLocator}/checkInvoices
Issue the next invoice for a policyPOST /policy/{policyLocator}/issueNextInvoice
Fetch a Policy SnapshotPOST /policies/{policyLocator}/snapshot
Fetch a Policy Coverage SummaryPOST /policies/{policyLocator}/coverageSummary
Upgrade a policy's product versionPATCH /policy/{policyLocator}/upgrade
Cancel a policyPOST /policy/{policyLocator}/cancel
Fetch a policy's cancellation valueGET /policy/{policyLocator}/cancellationValue
Withdraw a policyPOST /policy/{policyLocator}/withdraw

Basic Operations

Create a policy
POST /policy
    Request:
    NamePositionTypeRequired
    createRequestbodyPolicyCreateRequestrequired
    entitiesquerystringoptional
    entitiesAsOfTimestampquerytimestampoptional
    includeReplacedCharacteristicsquerybooleanoptional
    summarizeQuotesquerybooleanoptional
    Response: PolicyResponse
PolicyCreateRequest
required
policyholderLocator string
productName string

optional
overrideResourcesAsOfTimestamp timestamp
policyEndTimestamp timestamp
policyStartTimestamp timestamp
fieldValues map<string,[string]>
autofill [string]
currency string
finalize boolean
paymentScheduleName string
premiumReportName string
configVersion integer
PolicyResponse
required
locator string
policyholderLocator string
productLocator string
productName string
createdTimestamp timestamp
updatedTimestamp timestamp
originalContractStartTimestamp timestamp
originalContractEndTimestamp timestamp
effectiveContractEndTimestamp timestamp
exposures [ExposureResponse]
grossFees number
currency string
fees [FeeResponse]
configVersion integer
displayId string (deprecated)

optional
issuedTimestamp timestamp
overrideResourcesAsOfTimestamp timestamp
resourcesAsOfTimestamp timestamp
cancellation CancellationInfo
cashBalance CashBalanceResponse
grossFeesCurrency string
paymentScheduleName string
premiumReportName string
quoteLocator string
quoteSummary QuoteSummaryResponse

Note

  • The overrideResourcesAsOfTimestamp attribute should not be used before the Resource Management feature has been implemented.

  • When calling POST /policy, by default the quoteSummary will remain unpopulated in the response for performance reasons. To include a quote summary, set the query parameter summarizeQuotes=true.

  • The field displayId is deprecated. Use locator instead.

Important

The default for policies on create or update for finalization is finalize = true. To prevent immediate finalization and immutability, set finalize = false.

Fetch a policy
GET /policy/{policyLocator}
    Request:
    NamePositionTypeRequired
    entitiesquerystringoptional
    entitiesAsOfTimestampquerytimestampoptional
    includeReplacedCharacteristicsquerybooleanoptional
    policyLocatorpathstringrequired
    summarizeQuotesquerybooleanoptional
    Response: PolicyResponse

Note

  • By default, the quoteSummary will remain unpopulated in the response for performance reasons. To include a quote summary, set the query parameter summarizeQuotes=true.

  • entitiesAsOfTimestamp, includeReplacedCharacteristics, and entities query parameters control filtering of unrequired response elements prior to the “as of” timestamp. See Policy API Query Parameters for more details.

Update a draft policy
POST /policy/{policyLocator}/update
PolicyUpdateRequest
required
addFieldGroups [FieldGroupCreateRequest]
updateFieldGroups [FieldGroupUpdateRequest]
removeFieldGroups [string]
addExposures [ExposureCreateRequest]
removeExposures [string]

optional
effectiveContractEndTimestamp timestamp
effectiveContractStartTimestamp timestamp
overrideResourcesAsOfTimestamp timestamp
policyEndTimestamp timestamp
policyStartTimestamp timestamp
fieldValues map<string,[string]>
autofill [string]
finalize boolean
paymentScheduleName string
resetOverrideResourcesAsOfTimestamp boolean
Finalize a policy
POST /policy/{policyLocator}/finalize
    Request:
    NamePositionTypeRequired
    policyLocatorpathstringrequired
    Response: PolicyResponse
Issue a policy
POST /policy/{policyLocator}/issue
    Request:
    NamePositionTypeRequired
    policyLocatorpathstringrequired
    Response: PolicyResponse
Discard a policy
POST /policy/{policyLocator}/discard
    Request:
    NamePositionTypeRequired
    policyLocatorpathstringrequired
    Response: void

Exposures

ExposureCreateRequest
required
exposureName string

optional
fieldValues map<string,[string]>
DraftPolicyExposureUpdateRequest
required
addFieldGroups [FieldGroupCreateRequest]
updateFieldGroups [FieldGroupUpdateRequest]
removeFieldGroups [string]
addPerils [PerilCreateRequest]
updatePerils [PerilUpdateRequest]
exposureLocator string
removePerils [string]

optional
fieldValues map<string,[string]>
ExposureResponse
required
locator string
name string
displayId string
policyholderLocator string
policyLocator string
productLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
perils [PerilResponse]

Perils

PerilCreateRequest
required
name string

optional
locator string
fieldValues map<string,[string]>
deductible number
lumpSumPayment number
indemnityInAggregate string
indemnityPerEvent string
indemnityPerItem string
PerilUpdateRequest
required
fieldValues map<string,[string]>
addFieldGroups [FieldGroupCreateRequest]
updateFieldGroups [FieldGroupUpdateRequest]
removeFieldGroups [string]
perilLocator string

optional
deductible number
lumpSumPayment number
indemnityInAggregate string
indemnityPerEvent string
indemnityPerItem string
removeDeductible boolean
removeIndemnityInAggregate boolean
removeIndemnityPerEvent boolean
removeIndemnityPerItem boolean
removeLumpSumPayment boolean
PerilResponse
required
locator string
name string
displayId string
policyholderLocator string
policyLocator string
productLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
characteristics [PerilCharacteristicsResponse]
exposureLocator string
renewalGroup string

Characteristics

PolicyCharacteristicsResponse
required
locator string
policyholderLocator string
policyLocator string
productLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
startTimestamp timestamp
endTimestamp timestamp
policyEndTimestamp timestamp
policyStartTimestamp timestamp
fieldValues map<string,[string]>
fieldGroupsByLocator map<string,map<string,[string]>>
mediaByLocator map<string,Media>
taxGroups [TaxGroupResponse]

optional
issuedTimestamp timestamp
replacedTimestamp timestamp
grossPremium number
grossTaxes number
grossPremiumCurrency string
grossTaxesCurrency string
ExposureCharacteristicsResponse
required
locator string
policyholderLocator string
policyLocator string
productLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
startTimestamp timestamp
endTimestamp timestamp
fieldValues map<string,[string]>
exposureLocator string
fieldGroupsByLocator map<string,map<string,[string]>>
mediaByLocator map<string,Media>

optional
issuedTimestamp timestamp
replacedTimestamp timestamp
PerilCharacteristicsResponse
required
locator string
policyholderLocator string
policyLocator string
productLocator string
policyCharacteristicsLocator string
exposureCharacteristicsLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
coverageStartTimestamp timestamp
coverageEndTimestamp timestamp
fieldValues map<string,[string]>
fieldGroupsByLocator map<string,map<string,[string]>>
mediaByLocator map<string,Media>
perilLocator string
policyModificationLocator string

optional
issuedTimestamp timestamp
characteristicsAsOfTimestamp timestamp
replacedTimestamp timestamp
deductible number
lumpSumPayment number
monthPremium number
monthTechnicalPremium number
premium number
technicalPremium number
deductibleCurrency string
indemnityInAggregate string
indemnityInAggregateCurrency string
indemnityPerEvent string
indemnityPerEventCurrency string
indemnityPerItem string
indemnityPerItemCurrency string
lumpSumPaymentCurrency string
premiumCurrency string

Modifications

PolicyModificationResponse
required
locator string
name string
displayId string
policyholderLocator string
policyLocator string
productLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
exposureModifications [ExposureModificationResponse]
mediaByLocator map<string,Media>
newPolicyCharacteristicsLocators [string]
number integer
fieldGroupsByLocator map<string,map<string,[string]>> (deprecated)
fieldValues map<string,[string]> (deprecated)

optional
cancellationLocator string
issuedTimestamp timestamp
effectiveTimestamp timestamp
policyEndTimestamp timestamp
resourcesAsOfTimestamp timestamp
premiumChange number
automatedUnderwritingResult AutomatedUnderwritingResultResponse
cancellationName string
endorsementLocator string
newPolicyCharacteristicsLocator string
premiumChangeCurrency string
reinstatementLocator string
renewalLocator string
configVersion integer (deprecated)
ExposureModificationResponse
required
locator string
policyholderLocator string
policyLocator string
productLocator string
exposureLocator string
perilModifications [PerilModificationResponse]
policyModificationLocator string

optional
newExposureCharacteristicsLocator string
PerilModificationResponse
required
locator string
policyholderLocator string
policyLocator string
productLocator string
exposureModificationLocator string
perilLocator string

optional
premiumChange number
newPerilCharacteristicsLocator string
premiumChangeCurrency string
replacedPerilCharacteristicsLocator string

Field Groups

FieldGroupCreateRequest
required
fieldName string

optional
fieldValues map<string,[string]>
FieldGroupUpdateRequest
required
fieldGroupLocator string
fieldName string
fieldValues map<string,[string]>

Documents

Add a document to a policy
POST /policy/{policyLocator}/addDocument
    Request:
    NamePositionTypeRequired
    displayNamequerystringrequired
    documentformdatafilerequired
    documentTypequerystringrequired
    policyLocatorpathstringrequired
    Response: PolicyResponse

Upload a PDF or HTML file and add it to the documents attached to the specified policy. This will not cause an endorsement or other policy transaction.

Remove a document from a policy
POST /policy/{policyLocator}/removeDocument
  • Remove a user-uploaded document from a policy.

  • The policy must not be already issued.

PolicyDocumentResponse
required
locator string
displayName string
fileName string
type string pdf | html

optional
createdTimestamp timestamp
urlExpirationTimestamp timestamp
policyModificationLocator string
url string
PolicyDocumentRemoveRequest
required
documentLocator string

Underwriting

Fetch a policy's automated underwriting result
GET /policy/{policyLocator}/automatedUnderwritingResult
AutomatedUnderwritingResultResponse
required
decisionTimestamp timestamp
decision string accept | reject | none
notes [string]

Fees

Add or reverse fees
PATCH /policy/{policyLocator}/fees
FeeUpdateRequest
required
newFees [FeeCreateRequest]
reverseFees [string]
FeeCreateRequest
required
startTimestamp timestamp
endTimestamp timestamp
amount number
feeName string

optional
description string
FeeResponse
required
locator string
name string
startTimestamp timestamp
endTimestamp timestamp
amount number
description string
reversed boolean

optional
amountCurrency string
PolicyFeeSummaryResponse
required
fees [FeeResponse]

Pricing

Fetch a policy's pricing data
GET /policy/{policyLocator}/price
Price a policy
POST /policy/{policyLocator}/price
PolicyPriceResponse
required
grossCommissions number
grossFees number
grossPremium number
grossTaxes number
premiumsByExposureLocator map<string,number>
premiumsByPerilLocator map<string,number>
totalDue number
commissions [CommissionResponse]
exposurePrices [GetExposurePriceResponse]
fees [FeeResponse]
holdbacks [HoldbackResponse]
taxGroups [TaxGroupResponse]

optional
grossTechnicalPremium number
grossCommissionsCurrency string
grossFeesCurrency string
grossPremiumCurrency string
grossTaxesCurrency string
grossTechnicalPremiumCurrency string
totalDueCurrency string
GetPolicyPriceResponse
required
grossCommissions number
grossFees number
grossPremium number
grossTaxes number
total number
commissions [CommissionResponse]
exposurePrices [GetExposurePriceResponse]
fees [FeeResponse]
holdbacks [HoldbackResponse]
taxGroups [TaxGroupResponse]

optional
grossTechnicalPremium number
grossCommissionsCurrency string
grossFeesCurrency string
grossPremiumCurrency string
grossTaxesCurrency string
grossTechnicalPremiumCurrency string
totalCurrency string
GetExposurePriceResponse
required
locator string
name string
grossCommissions number
grossPremium number
grossTaxes number
total number
commissions [CommissionResponse]
perilPrices [GetPerilPriceResponse]
taxGroups [TaxGroupResponse]

optional
grossTechnicalPremium number
grossCommissionsCurrency string
grossPremiumCurrency string
grossTaxesCurrency string
grossTechnicalPremiumCurrency string
totalCurrency string
GetPerilPriceResponse
required
locator string
name string
grossCommissions number
grossTaxes number
premium number
total number
commissions [CommissionResponse]

optional
technicalPremium number
grossCommissionsCurrency string
grossTaxesCurrency string
premiumCurrency string
technicalPremiumCurrency string
totalCurrency string
CommissionResponse
required
amount number
recipient string

optional
amountCurrency string
TaxGroupResponse
required
name string
amount number

optional
amountCurrency string
PolicyPriceChangeResponse
required
grossCommissionsChange number
grossFeesChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossFees number
newGrossPremium number
newGrossTaxes number
newTotal number
totalChange number
exposurePrices [ExposurePriceChangeResponse]
holdbacks [HoldbackResponse]
taxGroups [TaxChangeResponse]
ExposurePriceChangeResponse
required
name string
grossCommissionsChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossPremium number
newGrossTaxes number
taxGroups [TaxChangeResponse]

optional
locator string
newlyAdded boolean
PerilPriceChangeResponse
required
name string
grossCommissionsChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossPremium number
newGrossTaxes number

optional
locator string
newlyAdded boolean
TaxChangeResponse
required
name string
change number
newAmount number
CommissionChangeResponse
required
amountChange number
newAmount number
recipient string
FeeChangeResponse
required
name string
amountChange number
newAmount number

optional
locator string
HoldbackResponse
required
locator string
cancellationLocator string
amount number
isReversed boolean
type string premium | tax | fee | commission | holdback | cash

optional
perilName string
perilCharacteristicsLocator string
commissionRecipient string
feeLocator string
feeName string
holdbackMetadata string
taxLocator string
taxName string

Invoicing and Financial Transactions

Change Payment Schedule
POST /policy/{policyLocator}/paymentSchedule
    Request:
    NamePositionTypeRequired
    paymentScheduleChangeRequestbodyPaymentScheduleChangeRequestrequired
    policyLocatorpathstringrequired
    Response: void
PaymentScheduleChangeRequest
required
newPaymentScheduleName string
Fetch a policy's invoices
GET /policy/{policyLocator}/checkInvoices
Issue the next invoice for a policy
POST /policy/{policyLocator}/issueNextInvoice
    Request:
    NamePositionTypeRequired
    policyLocatorpathstringrequired
    Response: PolicyResponse
  • This endpoint issues the next scheduled invoice for the policy (as visible from Check Invoices)

  • The invoice due date will be the same as if the invoice was issued automatically

Warning

The issue next invoice endpoint is not recommended for production policies.

CheckInvoicesResponse
required
futureInvoices [FutureInvoiceResponse]
generatedInvoices [GeneratedInvoiceResponse]
FutureInvoiceResponse
required
issueTimestamp timestamp
startTimestamp timestamp
endTimestamp timestamp
financialTransactions [FinancialTransactionResponse]

optional
dueTimestamp timestamp
writeOff boolean
GeneratedInvoiceResponse
required
financialTransactions [FinancialTransactionResponse]
PolicyInvoiceResponse
required
locator string
displayId string
policyLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
dueTimestamp timestamp
startTimestamp timestamp
endTimestamp timestamp
totalDue number
invoiceType string newBusiness | endorsement | renewal | cancellation | reinstatement | installment | premiumReporting | catchUp | other
payments [PaymentResponse]
settlementStatus string outstanding | settled
totalDueCurrency string
transactionIssued boolean

optional
policyModificationLocator string
premiumReportName string
settlementType string paid | writtenOff | zeroDue | invalidated | carriedForward
FinancialTransactionResponse
required
startTimestamp timestamp
endTimestamp timestamp
postedTimestamp timestamp
amount number
policyModificationLocator string
type string premium | tax | fee | commission | holdback | cash

optional
perilName string
perilCharacteristicsLocator string
amountCurrency string
commissionLocator string
commissionRecipient string
feeLocator string
feeName string
holdbackLocator string
taxLocator string
taxName string
PolicyInvoiceStatusAndTimeResponse
required
timestamp timestamp
status string unfulfilled | paid | writtenOff | zeroDue | invalidated | carriedForward

Snapshots and Coverage Summaries

Note

See Policy Snapshots and Coverage Summaries for details on using these endpoints.

Fetch a Policy Snapshot
POST /policies/{policyLocator}/snapshot
PolicySnapshotRequest
required
snapshotTimestamp timestamp

The snapshotTimestamp indicates the time at which you want the snapshot to be based. Policy transactions that were issued after this time will not be reflected in the response.

PolicySnapshotResponse
required
locator string
policyholderLocator string
productName string
snapshotTimestamp timestamp
ExposureSnapshotResponse
required
locator string
name string
PerilSnapshotResponse
required
locator string
name string
characteristics [PerilCharacteristicsResponse]
renewalGroup string
Fetch a Policy Coverage Summary
POST /policies/{policyLocator}/coverageSummary
CoverageSummaryRequest
required
coverageReferenceTimestamp timestamp

optional
policyHistoryTimestamp timestamp
PolicyCoverageSummaryResponse
required
locator string
policyholderLocator string
productName string
coverageReferenceTimestamp timestamp
policyHistoryTimestamp timestamp

optional
ExposureCoverageSummaryResponse
required
locator string
name string
PerilCoverageSummaryResponse
required
locator string
name string
renewalGroup string

Policy Product Upgrade

Upgrade a policy's product version
PATCH /policy/{policyLocator}/upgrade
PolicyConfigUpgradeRequest
required
newConfigVersion integer
PolicyConfigUpgradeResponse
required
policyLocator string
newConfigVersion integer
oldConfigVersion integer

Legacy Endpoints

Cancel a policy
POST /policy/{policyLocator}/cancel
CancellationValueResponse
required
value number
balanceAfterCancellation number
grossCommissionsChange number
grossFeesChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossFees number
newGrossPremium number
newGrossTaxes number
newTotal number
totalChange number
exposurePrices [ExposurePriceChangeResponse]
taxGroups [TaxChangeResponse]
PolicyCancellationIssueRequest
required
coverageEndTimestamp timestamp
CancellationInfo
required
effectiveTimestamp timestamp
modificationLocator string
modificationName string
Fetch a policy's cancellation value
GET /policy/{policyLocator}/cancellationValue
    Request:
    NamePositionTypeRequired
    coverageEndTimestampquerytimestamprequired
    policyLocatorpathstringrequired
Withdraw a policy
POST /policy/{policyLocator}/withdraw
    Request:
    NamePositionTypeRequired
    policyLocatorpathstringrequired
    Response: PolicyResponse