Policy API

Endpoint Index

Action	Endpoint
Create a policy	POST /policy
Fetch a policy	GET /policy/{policyLocator}
Update a draft policy	POST /policy/{policyLocator}/update
Finalize a policy	POST /policy/{policyLocator}/finalize
Issue a policy	POST /policy/{policyLocator}/issue
Discard a policy	POST /policy/{policyLocator}/discard
Add a document to a policy	POST /policy/{policyLocator}/addDocument
Remove a document from a policy	POST /policy/{policyLocator}/removeDocument
Fetch a policy's automated underwriting result	GET /policy/{policyLocator}/automatedUnderwritingResult
Add or reverse fees	PATCH /policy/{policyLocator}/fees
Fetch a policy's pricing data	GET /policy/{policyLocator}/price
Price a policy	POST /policy/{policyLocator}/price
Change Payment Schedule	POST /policy/{policyLocator}/paymentSchedule
Fetch a policy's invoices	GET /policy/{policyLocator}/checkInvoices
Issue the next invoice for a policy	POST /policy/{policyLocator}/issueNextInvoice
Fetch a Policy Snapshot	POST /policies/{policyLocator}/snapshot
Fetch a Policy Coverage Summary	POST /policies/{policyLocator}/coverageSummary
Upgrade a policy's product version	PATCH /policy/{policyLocator}/upgrade
Cancel a policy	POST /policy/{policyLocator}/cancel
Fetch a policy's cancellation value	GET /policy/{policyLocator}/cancellationValue
Withdraw a policy	POST /policy/{policyLocator}/withdraw

Basic Operations

Create a policy¶

POST /policy

Request:

Name	Position	Type	Required
createRequest	body	PolicyCreateRequest	required
summarizeQuotes	query	boolean	optional

Response: PolicyResponse

PolicyCreateRequest¶

required
policyholderLocator string
productName string

optional
policyEndTimestamp timestamp
policyStartTimestamp timestamp
exposures [ExposureCreateRequest]
fieldValues map<string,[string]>
autofill [string]
currency string
fieldGroups [FieldGroupCreateRequest]
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
characteristics [PolicyCharacteristicsResponse]
modifications [PolicyModificationResponse]
exposures [ExposureResponse]
documents [PolicyDocumentResponse]
invoices [PolicyInvoiceResponse]
grossFees number
currency string
fees [FeeResponse]
configVersion integer
displayId string (deprecated)

optional
issuedTimestamp timestamp
cancellation CancellationInfo
grossFeesCurrency string
paymentScheduleName string
premiumReportName string
quoteLocator string
quoteSummary QuoteSummaryResponse

Note

When calling POST /policy and GET /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:

Name	Position	Type	Required
policyLocator	path	string	required
summarizeQuotes	query	boolean	optional

Response: PolicyResponse

Update a draft policy¶

POST /policy/{policyLocator}/update

Request:

Name	Position	Type	Required
policyLocator	path	string	required
updateRequest	body	PolicyUpdateRequest	required

Response: PolicyResponse

PolicyUpdateRequest¶

required
addFieldGroups [FieldGroupCreateRequest]
updateFieldGroups [FieldGroupUpdateRequest]
removeFieldGroups [string]
addExposures [ExposureCreateRequest]
updateExposures [DraftPolicyExposureUpdateRequest]
removeExposures [string]

optional
effectiveContractEndTimestamp timestamp
effectiveContractStartTimestamp timestamp
policyEndTimestamp timestamp
policyStartTimestamp timestamp
fieldValues map<string,[string]>
autofill [string]
finalize boolean
paymentScheduleName string

Finalize a policy¶

POST /policy/{policyLocator}/finalize

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: PolicyResponse

Issue a policy¶

POST /policy/{policyLocator}/issue

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: PolicyResponse

Discard a policy¶

POST /policy/{policyLocator}/discard

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: void

Exposures

ExposureCreateRequest¶

required
exposureName string

optional
perils [PerilCreateRequest]
fieldValues map<string,[string]>
fieldGroups [FieldGroupCreateRequest]

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
characteristics [ExposureCharacteristicsResponse]
perils [PerilResponse]

Perils

PerilCreateRequest¶

required
name string

optional
locator string
fieldValues map<string,[string]>
deductible number
lumpSumPayment number
fieldGroups [FieldGroupCreateRequest]
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
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
issuedTimestamp timestamp
effectiveTimestamp timestamp
policyEndTimestamp timestamp
premiumChange number
automatedUnderwritingResult AutomatedUnderwritingResultResponse
cancellationName string
endorsementLocator string
newPolicyCharacteristicsLocator string
premiumChangeCurrency 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:

Name	Position	Type	Required
displayName	query	string	required
document	formdata	file	required
documentType	query	string	required
policyLocator	path	string	required

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

Request:

Name	Position	Type	Required
policyLocator	path	string	required
request	body	PolicyDocumentRemoveRequest	required

Response: PolicyResponse

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

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: AutomatedUnderwritingResultResponse

AutomatedUnderwritingResultResponse¶

required
decisionTimestamp timestamp
decision string accept | reject | none
notes [string]

Fees

Add or reverse fees¶

PATCH /policy/{policyLocator}/fees

Request:

Name	Position	Type	Required
policyLocator	path	string	required
req	body	FeeUpdateRequest	required

Response: PolicyFeeSummaryResponse

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

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: GetPolicyPriceResponse

Price a policy¶

POST /policy/{policyLocator}/price

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: PolicyPriceResponse

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]
taxes [TaxGroupResponse]

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
commissions [CommissionChangeResponse]
exposurePrices [ExposurePriceChangeResponse]
fees [FeeChangeResponse]
holdbacks [HoldbackResponse]
taxGroups [TaxChangeResponse]

ExposurePriceChangeResponse¶

required
name string
grossCommissionsChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossPremium number
newGrossTaxes number
commissions [CommissionChangeResponse]
perilPrices [PerilPriceChangeResponse]
taxGroups [TaxChangeResponse]

optional
locator string
newlyAdded boolean

PerilPriceChangeResponse¶

required
name string
grossCommissionsChange number
grossPremiumChange number
grossTaxesChange number
newGrossCommissions number
newGrossPremium number
newGrossTaxes number
commissions [CommissionChangeResponse]
taxes [TaxChangeResponse]

optional
locator string

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

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:

Name	Position	Type	Required
paymentScheduleChangeRequest	body	PaymentScheduleChangeRequest	required
policyLocator	path	string	required

Response: void

PaymentScheduleChangeRequest¶

required
newPaymentScheduleName string

Fetch a policy's invoices¶

GET /policy/{policyLocator}/checkInvoices

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: CheckInvoicesResponse

Issue the next invoice for a policy¶

POST /policy/{policyLocator}/issueNextInvoice

Request:

Name	Position	Type	Required
policyLocator	path	string	required

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]
invoice PolicyInvoiceResponse

PolicyInvoiceResponse¶

required
locator string
displayId string
policyLocator string
createdTimestamp timestamp
updatedTimestamp timestamp
dueTimestamp timestamp
startTimestamp timestamp
endTimestamp timestamp
documents [PolicyDocumentResponse]
totalDue number
invoiceType string newBusiness | endorsement | renewal | cancellation | reinstatement | installment | premiumReporting | other
payments [PaymentResponse]
settlementStatus string outstanding | settled
statuses [PolicyInvoiceStatusAndTimeResponse]
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

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

Request:

Name	Position	Type	Required
policyLocator	path	string	required
request	body	PolicySnapshotRequest	required

Response: PolicySnapshotResponse

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
characteristics [PolicyCharacteristicsResponse]
exposures [ExposureSnapshotResponse]

ExposureSnapshotResponse¶

required
locator string
name string
characteristics [ExposureCharacteristicsResponse]
perils [PerilSnapshotResponse]

PerilSnapshotResponse¶

required
locator string
name string
characteristics [PerilCharacteristicsResponse]
renewalGroup string

Fetch a Policy Coverage Summary¶

POST /policies/{policyLocator}/coverageSummary

Request:

Name	Position	Type	Required
policyLocator	path	string	required
request	body	CoverageSummaryRequest	required

Response: PolicyCoverageSummaryResponse

CoverageSummaryRequest¶

required
coverageReferenceTimestamp timestamp

optional
policyHistoryTimestamp timestamp

PolicyCoverageSummaryResponse¶

required
locator string
policyholderLocator string
productName string
coverageReferenceTimestamp timestamp
policyHistoryTimestamp timestamp
exposures [ExposureCoverageSummaryResponse]
documents [PolicyDocumentResponse]

optional
characteristics PolicyCharacteristicsResponse

ExposureCoverageSummaryResponse¶

required
locator string
name string
characteristics ExposureCharacteristicsResponse
perils [PerilCoverageSummaryResponse]

PerilCoverageSummaryResponse¶

required
locator string
name string
characteristics PerilCharacteristicsResponse
renewalGroup string

Policy Product Upgrade

Upgrade a policy's product version¶

PATCH /policy/{policyLocator}/upgrade

Request:

Name	Position	Type	Required
policyLocator	path	string	required
req	body	PolicyConfigUpgradeRequest	required

Response: PolicyConfigUpgradeResponse

PolicyConfigUpgradeRequest¶

required
newConfigVersion integer

PolicyConfigUpgradeResponse¶

required
policyLocator string
newConfigVersion integer
oldConfigVersion integer

Legacy Endpoints

Cancel a policy¶

POST /policy/{policyLocator}/cancel

Request:

Name	Position	Type	Required
policyLocator	path	string	required
request	body	PolicyCancellationIssueRequest	required

Response: PolicyResponse

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
commissions [CommissionChangeResponse]
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:

Name	Position	Type	Required
coverageEndTimestamp	query	timestamp	required
policyLocator	path	string	required

Response: CancellationValueResponse

Withdraw a policy¶

POST /policy/{policyLocator}/withdraw

Request:

Name	Position	Type	Required
policyLocator	path	string	required

Response: PolicyResponse