Release Notes

Note

The structure and use of the API does not change when names of entities or endpoint operation IDs change. These changes are typically made for clarity and consistency.

All changes to the API listed here are also reflected in our Open API definition file.

October 9, 2024

New Feature Guides

Other Changes

Added new Fetch Tenant Level Cash Balance endpoint.
Added new property clearedAt to UnderwritingFlag.

October 2, 2024

Added the property category to ElementResponse, to indicate in which of the main categories the element is. This can be product, policyLine, exposureGroup, exposure, or coverage.
Added the Format Config endpoint to convert a configuration’s property casing to match requrements.
Added the resetToDraft query parameter for the Reset Transaction endpoint. If true, then the transaction will revert to draft state and the generated segment data, including elements and data, will be discarded. If false (the default), then the transaction will revert to initialized state and the segment data will be retained. This is useful to preserve the locator data for generated elements.

September 25, 2024

New Getting Started Guide!

See the new Getting Started Guide for a step-by-step introduction to configuring and using Socotra.

New Migration Feature Guide

See the new Migration Feature Guide for more details about data migration projects.

Invoice Documents

Documents can now be configured to renender when invoices are generated, similarly to how policy documents are created.
See the Invoice Rendering topic for details.

Other Changes

Enabled support for reinstatement with a gap.
Added a new feature guide for automatic handling of excess credits.
Extended the Quick Quotes Feature Guide with additional details.
Clarified in the Rounding Service Feature Guide that the configuration for rounding mode is limited to data extensions.
Marked the following properties as optional:
- UnderwritingFlagResponse: elementLocator
- QuoteUnderwritingFlagsResponse: clearedFlags

September 18, 2024

External Documents

You can now attach documents created from outside Socotra to quotes, policies, terms, segments, and transactions. See the Documents Feature Guide and Documents API Guide for details.

Other Changes

On PolicyResponse, the latestSegmentLocator has been added to indicated the last segment on the policy based on issued transactions.
The TermResponse entity has added property termNumber.
The Add Elements To Policy with Transaction endpoint’s request type has been changed to ElementResponse[].
On ConfigurationRef, the defaultRegion property has been deprecated and marked as optional.
For these configuration entities, the displayName is now marked as optional.

September 11, 2024

On PolicyTransactionResponse, the property acceptedTime has been added, the properties aggregatedTransactions and changeInstructions have now marked as optional.
On QuoteResponse, the deprecated property boundTime has been removed in favor of the new property acceptedTime.
On TransactionPriceResponse, the property aggregatedTransactions is now marked as optional.

September 4, 2024

Optional Properties

The following properties are now marked as optional:

AccountResponse: autoRenewalPlanName, delinquencyPlanName, excessCreditPlanName, shortfallTolerancePlanName, invoiceDocument, preferences, region
QuoteCreateRequest: durationBasis, billingLevel, billingTrigger, region
ElementRef: coverageTerms, data
ElementResponse: coverageTerms, data
TenantResponse: description
QuoteResponse: static
AccountCreateRequest: region
AccountUpdateReplaceDataRequest: region

Billing Triggers

The “Billing Trigger” setting is being removed, and the following entities now have the property billingTrigger deprecated.

In addition:

On ConfigurationRef and ProductRef, defaultBillingTrigger is deprecated.
The endpoint Update Policy Billing Trigger is deprecated.
The entity BillingTriggerUpdateRequest is deprecated.

Other Change

On DocumentSummary, the property documentInstanceState has been added, and the equivalent property state has been deprecated.

August 28, 2024

The following state properties have been changed, from state:
- AccountResponse: accountState
- QuickQuoteResponse: quickQuoteState
- QuickQuotePriceResponse: quickQuoteState
- InvoiceResponse: invoiceState
- DocumentInstanceResponse: documentInstanceState
The endpoints Preview Invoices for Quote and Preview Invoices for Transaction have had the property includeZeroAmountInvoices added, and excludeOtherPolicies has been removed.
The endpoint Fetch Transaction Segments has been deprecated in favor of Fetch Transaction Segment because transactions can have a maximum of a single segment.
The entity DocumentInstanceResponse has new properties category and external.

August 21, 2024

Diaries

Diaries are a new feature that enables a running narrative to be attached to individual entities. The following endpoints have been added:

The following entities are used in the above endpoints:

For now, diaries are enabled for quotes, policies, and policy transactions. Other entities will be enabled in the future.

See the Diaries Feature Guide for more information.

Regions

Regions are now supported. The new region property has been added to:

Also, defaultRegion has been added to ConfigurationRef.

Changes to Paged List Fetch Semantics

When fetching entities with any of the following endpoints, a new query parameter is available called extended. Setting extended to true means that the return object will not be a bare array of entities, but rather a List Contents object that includes an indicator that the list is complete. The following endpoints have been changed:

Fetch Multiple Accounts returns AccountListResponse.
Fetch Quotes for Account, Fetch All Quotes In Group, and Fetch Quotes In a Tenant return QuoteListResponse.
Fetch Multiple Quick Quotes and Fetch Quick Quotes for a Group return QuickQuoteListResponse.
Fetch Policies for Account returns PolicyListResponse.
Fetch Policy Snapshots for an Account returns PolicySnapshotListResponse.
Fetch Issued Transactions returns PolicyTransactionListResponse.
Fetch Multiple Terms returns TermListResponse.

Note

Later, the extended property will be removed and the default behavior will be as if it were true.

Auto Transaction Rebasing

Before, transactions were always invalidated when a transaction on another branch became issued. Now, these transactions are automatically rebased on to the new, latest issued transaction. This behavior can be bypassed by settng the autoRebase query paramter to false when using the Issue Transaction endpoint.

Other Changes

The following entity properties have been marked as optional:

AuthTokenResponse: permissions and tenants
ElementResponse: coveragesTerms and elements
PolicyResponse: branchHeadTransactionLocators

July 31, 2024

Quick Quotes

Quick Quotes are a lightweight mechanism for quotation without full underwriting support or document generation. Element extension data for quick quotes can be a subset of that used on a full quote.

The following endpoints have been added:

In support of the above endpoints, the following new entities are used:

Account Level Billing

Account level billing is activated by setting the billingLevel of the account, policy, or quote to account. If a policy or quote uses inherit for the billingLevel, it will defer to the account for the setting.

The following endpoints have been added to modify the billing level:

Each of these endpoints takes a UpdateBillingLevelRequest entity.

In addition, the following entities have added a billingLevel property:

Policy Transaction Branching

Policy transaction branching is done by setting the baseLocator of the transaction to a transaction other than the most recently created transaction. The following endpoints that create policy transactions now have a baseLocator parameter:

And the following entity has a baseLocator property:

PolicyTransactionReversalRequest

Configuration Changes

Added the property delinquencyLevel, and removed properties baseLapseOn and lapseConflictHandling from DelinquencyPlanRef
Added the property defaultBackdatedInstallmentsBilling to ConfigurationRef.
Deprecated the billingPlans and defaultBillingPlan properties on ConfigurationRef, and defaultBillingPlan on ProductRef. These will be removed in an upcoming release.

Other Changes

Endpoints which return a streaming response now show the type of object in the stream. So StreamingResponseBody now is shown as StreamingResponseBody<string>, StreamingResponseBody<ZipFile>, etc.
The InvoiceItemResponse’s installmentItemsLocators property has been renamed to installmentItemLocators, and has added properties invoiceLocator and transactionLocator. Also, the reversalOfLocator property has been removed.
Added a timezone property to InvoiceResponse
Added the preemptingLapseTransactionLocator property to DelinquencyReference.
Added properties realizedAt, reversalReason, and reversedAt to CreditResponse.
Added the boolean property reversalLattice to InstallmentLatticeResponse, and made the settingsLocator property optional.
On QuoteResponse and QuoteGroupAssignmentRequest, renamed the quoteGroupLocator property to groupLocator.
On PolicyResponse, added the properties latestTermLocator and billingLevel.
On AccountResponse, AccountCreateRequest, AccountUpdateRequest, and AccountUpdateReplaceDataRequest, added the properties billingLevel and invoiceDocument.
Added the Fetch Invoices for Account endpoint.

July 24, 2024

Internal changes only for this release.

July 1, 2024

Stateless Operations

Stateless operations are a way to determine the validatability, pricing, and underwriting for a quote or policy transaction without changing its state. The following endpoints now have a stateless parameter added to generate the results of the call without a state change:

Other endpoints will also be updated with a stateless parameter in upcoming releases.

Invoices and Installments

On InvoiceItemResponse, added new properties invoiceLocator and transactionLocator, and changed the installmentItemsLocators property to be called installmentItemLocators, and made the elementStaticLocator property required.
On InvoiceResponse, made the startTime and endtime properties required, and changed the type of the currency property to string.
On InstallmentItemResponse, removed the property reversalOfLocator.
On InstallmentLatticeResponse, added the property reversalLattice, and made the settingsLocator property required.

Other Changes

Added a new Fetch Invoice Details endpoint for retreiving granular information about the contents of invoices. The response includes the new entities InvoiceDetailsResponse, PolicyInvoiceSummary, InvoiceItemSummary, and InstallmentItemSummary.
Added the Preview Invoices for Quote endpoint, with InvoicePreviewResponse and InvoiceItemPreview entities.
Added the Fetch Preferences for a Transaction endpoint.
Added the property preemptingLapseTransactionLocator to DelinquencyReference, which indicates that some other delinquency’s lapse transaction has taken precedence over this delinquency’s lapse transaction.
Added the property delinquencylevel to DelinquencySettings
On DelinquencyPlanRef, added the property delinquencyLevel and removed the properties baseLapseOn and lapseConflictHandling.
On PolicyResponse, added the property latestTermLocator and made the startTime and endTime properties required.
On QuoteGroupAssignmentRequest, changed the name of the quoteGroupLocator property to groupLocator.

June 10, 2024

Policies

Added the properties startTime and endTime to PolicyResponse. These indicate the start and end of the policy based on issued transactions only.

Invoices and Payments

Added endpoint Fetch Invoices Targeted By a Payment
Added endpoint Fetch Invoices Targeted By a Credit Distribution
Added the property unsettledTime to InvoiceResponse, to indicate when a settled invoice became unsettled due to a payment reversal.
The property elementStaticLocator has been added to the InvoiceItemResponse entity.

Installments

The reversalOfTransactionLocator, tenantLocator, invalidated, originationType, and refused properties have been removed from InstallmentResponse
The reversedByInstallmentItemLocator and tenantLocator properties have been removed from InstallmentItemResponse
The tenantLocator property has been removed from InstallmentLatticeResponse

Stateless Operations

These endpoints now have a boolean stateless property to allow calculation of pricing or underwriting data without changing the state of the associated quote or policy:

Underwriting

The responses for quote and policy transaction underwriting have been changed:

Underwrite Quote now returns a QuoteUnderwritingResponse
Underwrite Transaction now returns a TransactionUnderwritingResponse

Accounting

The “Cash” T-Accounts that represent cash inflows and outflows from the system are now managed at the customer account level.
These are accessed through the new Fetch a Ledger Cash Account and Fetch Multiple Ledger Cash Accounts endpoints.
The tenant-wide cash account has been removed and so the GET /billing/{tenantLocator}/accounting/ledgerAccounts/cash endpoint has been removed as well.

Delinquency

The properties graceEndAt and lapseTransactionEffectiveDate properties have been added to DelinquencyResponse
The references property is now optional on DelinquencyResponse
On DelinquencyPlanRef the properties advanceLapseTo and lapseTransactionType are now optional.
The properties executedAt and reversedAt have been added to CreditDistributionResponse and PaymentResponse

Aux Data

On AuxDataResponse the property auxDataSettingsName is now optional.
On AuxDataKey the auxDataSettingsName property is now optional.

Data Extension Constraints

These Data Extension Constraints endpoints are now accessed with POST API calls:

Other Changes

Added the parameter includeReversed to the Fetch Payments for an Invoice, Fetch Credits for an Invoice, and Fetch Credit Distributions for an Invoice endpoints to include those response items that have been previously reversed.
Added the property preferences to TransactionSnapshotResponse.
Added the property searchSummary to SearchResultResponse.
Removed the property transactionLocator from SegmentResponse.
Removed the properties rootLocator and tenantLocator from ElementResponse.
Added the property updatedAt to TenantResponse.
On ProductRef the properties defaultAutoRenewalPlan, defaultDelinquencyPlan, and defaultShortfallTolerancePlan are now optional.

May 23, 2024

Users

Added the Fetch Multiple Basic Users endpoint to return a streamlined user response, which allows for a larger page size. This endpoint returns an array of UserBasicResponse entities.
Renamed the fetchUsersByBusinessAccount endpoint to Fetch Multiple Users.

Excess Credits

The Excess Credits feature is forthcoming to handle excess customer credits held in a credit balance.

Added the excessCreditPlans and defaultExcessCreditPlan properties to ConfigurationRef, and added with the ExcessCreditPlanRef entity.
Added the excessCreditPlanName property to AccountCreateRequest, AccountResponse, AccountUpdateRequest, and AccountUpdateReplaceDataRequest.

Open API Definitions

A top level property in the Open API definition file was erronously called externalDocuments rather than its proper name externalDocs. This has been corrected. (This property is not currenly used as so contains an empty array.)

Other Changes

Clarified that the references property of DelinquencyResponse will only be populated when fetching a single delinquency entity. Accordingly marked references as optional.
Renamed the listByTransactionLocator endpoint to Fetch Installments for Policy Transaction
The DocumentInstanceResponse entity has the following properties marked as optional: policyLocator, referenceDocumentLocator, segmentLocator, termLocator, transactionLocator, name, staticName, documentFormat, processingErrors, readyAt, and createdBy.

May 20, 2024

Event Stream Data Definition

Information about the data contained within each payload is now on the Event Definitions Page.

May 17, 2024

Deprecations

The following entity properties are now deprecated and will be removed in a future release:

ConfigurationRef: defaultAnchorMode, defaultBillingLevel, defaultDueLeadDays, defaultLapseType, regions
ChargeRef: displayName
ElementRef: pluralType
ProductRef: pluralType
ParamsChangeInstructionCreateRequest: inheritSettings, billingModeChange
ParamsChangeInstructionResponse: inheritSettings, billingModeChange

Static Data

Added the parameter includeStaticData to the Fetch Quotes for Account and Fetch Policies for Account endpoints.

Other Changes

On ParamsChangeInstructionCreateRequest and ParamsChangeInstructionResponse:
- The triggerBillingChange property has been added, to replace billingModeChange
- The preferences and newPolicyEndTime properties are now optional.

May 15, 2024

Renewal Management and Auto-Renewal

There is a new Renewal Management API which supports the upcoming renewal management feature, including automatic renewal functionality.
A feature guide for renewal management is forthcoming.

Resources

Added the byStaticName and date parameter to the Fetch Resource and Fetch Secret endpoints for finer control of resource retreival.
The Fetch Document Template endpoint now returns a streaming response rather than a string.

Policy Snapshots

Added the Fetch Policy Snapshots for an Account endpoint.
Added document information with the documentSummary property on SubsegmentSummary

Credits

Added the Fetch Credits endpoint to fetch credits across an entire tenant.

“List” Endpoints

Changed the path to the following endpoints that return multiple endpoints for greater consistency:

Fetch Payments for an Invoice: /billing/{tenantLocator}/invoices/{locator}/payments/list
Fetch Credits for an Invoice: /billing/{tenantLocator}/invoices/{locator}/credits/list
Fetch Credit Distributions for an Invoice /billing/{tenantLocator}/invoices/{locator}/creditDistributions/list

Other Changes

ElementResponse now has an originalEffectiveTime property which shows when that element was first added to the policy.
On the Fetch Term Summary By Term Number endpoint, changed the number parameter to termNumber.
Added a description parameter to the Create Tenant endpoint.
On the Fetch Invoices for Policy and Fetch Invoices for Quote endpoints, added the includeZeroAmountInvoices parameter for filtering. The default is false.
On UnderwritingFlag, removed properties createdBy, createdTime, clearedBy clearedTime.
On TransactionPriceResponse, changed the pricingItems property to now be charges.
On InstallmentSettings, the maxInstallmentsPerTerm property is now optional.

May 1, 2024

Charges

On the week of May 6, 2024, there will be a change that requires configuration for which charges can be attached to elements. Each element definition must declare the charges that apply. ElementRef and ProductRef now have a charges property, which is an array of the charge types.

Important

All the applicable charges must be returned by the rating plugin, and only those charges can be applied; otherwise, the rating call will fail and the policy transaction or quote will fail to reach the priced state.

Documents

Documents may now be managed and retreived by the entity they are attached to with these endpoints:
- Fetch Documents for Segment
- Fetch Documents for Transaction
- Fetch Documents for Quote (previously named fetchDocumentsByQuote)
- Fetch Documents Job for Segment
- Fetch Documents Job for Transaction
- Fetch Documents Job for Quote (previously named fetchQuoteDocumentsJob)
- Fetch Multiple Documents Jobs for Segment
- Fetch Multiple Documents Jobs for Transaction
- Fetch Multiple Documents Jobs for Quote (previously named getQuoteDocumentsJobs)
- Trigger Timed Out Documents Job for Segment
- Trigger Timed Out Documents Job for Transaction
- Trigger Timed Out Documents Job for Quote (previously named triggerTimedOutQuoteJob)
The DocumentInstanceResponse property has a new policyLocator property.
The fetchSource endpoint has been renamed to Fetch Source for Document

Note

Policy documents are attatched to either policy segments or transactions, depending on scope rules

April 28, 2024

Feature Guides

New feature guides have been added for these topics:

Along with these is an entirely set of configuration guides for plugins, including rating, validation, underwriting, precommit, and more.

Search

Search now has provisions for opting entity properties into or out of the search index:

The property defaultSearchable has been added to ConfigurationRef, ProductRef, ElementRef, AccountRef, and DataTypeRef.
The property searchable has been added to PropertyRef.

Password Policies

Password policies now have editable settings:

The Fetch Password Policy and Update Password Policy can be used to find and update the individual settings. The payloads for these are PasswordPolicyResponse and PasswordPolicyUpdateRequest, respectively.
Settings include:
- Minimum and maximum overall password length
- The minimum number of uppercase letters, lowercase letters, numbers, and/or symbols
- password expiration after a given number of days
- Restrictions on reusing passwords before they are a certain number of days old

April 23, 2024

Payments

Added Fetch Payments for an Invoice endpoint.

Write-Offs

Added fetch endpoints:

Other Changes

Added property validationResult to PolicyResponse and AccountResponse
Added configuration for staticData to ProductRef
Deprecated endpoints Fetch Multiple Snapshots and Fetch Quotes In a Tenant
Added Fetch Policy Segment endpoint and deprecated Fetch Policy Segment Ex

Feature Guides

Added new feature guides:

April 17, 2024

Optional and Required Properties

The process for determining whether properties on entities were “required” (i.e. must be set on requests, or will always be set on responses) has moved from a manual to automated process. As a result of this some fields have changed from being indicated as required (with no suffix on their type name), or optional (with a ? suffix on the type name.)

Write-Offs

Added endpoints for write-off of invoices:

Term Summary

Term Summaries are views of the term based on issued transactions, showing in-force coverage only. This essentially flattens the transactions that affect the term into a single series of segments, such that the segments cover the entire term without overlaps or time periods without segments. This is useful to understand the state of the term without constructing it from the transaction stack.

The Fetch Term Summary By Term Locator and Fetch Term Summary By Term Number endpoints fetch the overall term summary, and contains summary objects for segments and elements. Extension data and charge information is included in the element summary.

Other Changes

The roundingMode property on PropertyRef has changed its enumeration values to use camel case: ceiling, down, floor, halfDown, halfEven, halfUp-up

April 12, 2024

Search

Added the Fetch Additional Search Results By Token endpoint
Added offset and count parameters to Fetch Search Results endpoint
Added properties offset, count, and searchToken to SearchServiceResponse, and removed page
Renamed the locator property on SearchResultResponse to searchEntityLocator

Invoicing

Added property installmentsItemsLocator to InvoiceResponse, and removed invoiceLocator and installmentItems
Added properties originationType, and refused, and invalidated to InstallmentResponse
Added property autoRenewalLocator to TermResponse

Other Changes

Added a Reinstatments Feature Guide
Added the Fetch Multiple Snapshots endpoint
Renamed the TransactionSnapshot entity to TransactionSnapshotResponse
Added parameter accountLocator to Fetch Multiple Payments, Fetch Multiple Disbursements and Fetch Multiple Credit Distributions endpoints
Added property preferences to AccountCreateRequest, AccountUpdateRequest, AccountUpdateReplaceDataRequest, and AccountResponse

Older Changes

See the release notes archive for older release notes.