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.

April 16, 2025

Policy Status

You can now view a policy’s status and stay apprised of status changes via the event stream. See the Policy Status Guide for details.

Note that policy statuses will not be backfilled; statuses will only be included for new policies and when transactions to existing policies prompt the platform to update the status.

Bug Fixes

Fixed a bug preventing documents from generating as expected on reversal and out-of-sequence (OOS) transactions.
Constraint table lookups with decimal values as keys will now work as expected, with a value-based test for equality. For example, if a table has a key value 340.98000, values 340.98000, 340.980, and 340.98 will match it.

April 9, 2025

Search Update

Searches by policy locator or account locator now include any associated first notice of loss (FNOL) records.

More Contact Associations

Contacts can now be linked to policies, quotes, and quick quotes.

Ad-Hoc Execution of Precommit Plugin

The precommit plugin can be invoked manually via API for draft quotes and draft or initialized transactions.

Full Stateless Pricing of Quote and Transactions

The previews feature has been expanded to allow for stateless pricing of quotes and transactions. See the Quotes API and Policy Transactions API for preview endpoint details.

Bug Fixes

Updated logic to ensure that data masking rules are followed for policy change transactions; for example, a user with a lower-privilege masking level cannot add coverages that have fields restricted above that user’s level.
Users with a certain masking level are allowed to modify fields on entities at that level or below, even if the element has some data extensions at a higher masking level.
Fixed unexpected 500 error on calls to Fetch Documents Job for Quote.
Configuration redeployment will now succeed if a regular expression rule for a field is removed, effectively widening allowed values for the field.
Add Elements To Quick Quote persists newly added elements as expected.
It is now possible to alter a payment’s paymentMode from aggregate to normal when using Update Payment Overwrite Data to update a payment.

April 2, 2025

Notice: Classic Early Invoicing Endpoint Deprecation

Over the last few months, we have been working on some upcoming features related to flat charges and invoice fees. To provide the best possible API design as part of this, we are making some API changes.

The existing Fetch Early Invoicing Job and Fetch Early Invoicing Jobs for Account endpoints will be removed as of the April 30th 2025 release. See the deprecation notice from February 12, 2025.
The existing Fetch Invoicing Job and Fetch Invoicing Jobs for Account endpoints have been refactored to accommodate both early and immediate triggers for invoice generation.

Internal changes only for this release.

March 26, 2025

New Features

Aggregate payments allow you spread payments across accounts, supporting a wide range of use cases without compromising the ability to trace cash flows through the system.
With flat charges, you can invoice charges directly through the billing system and easily handle a variety of fee arrangements.
Previews allow you to view the outcome of certain key operations without committing to the changes.

Bug Fixes

Fixed a bug causing access tokens with an expiresAt in the future from being accepted as expected.
suppressRenderingData now works as expected for all applicable Documents API endpoints, including Fetch Documents for Transaction.

March 19, 2025

Internal changes only for this release.

March 12, 2025

New Feature: Data Lake Delta Files

Easily sync Socotra Data Lake tables with your own infrastructure using Data Lake Delta Files! This feature allows you to list and retrieve SQL-based Data Lake diffs, ensuring accurate and efficient table replication into your own data platform.

New Data Lake Entities: Billing

Data Lake now exposes a number of billing tables. See the updated schema and guide for details.

Configuration Deployments API Update

You can now upload configuration files with brackets ([]) in the filename.

Classic Endpoint List Behavior Deprecation

Over the last few months, we have posted notices about impending updates to our list endpoint behavior. The “classic” behavior for list endpoints is to return a simple array of objects; however, to better facilitate pagination, we have established a new convention in which list endpoints will return an object with a listComplete property and the items array (example: InvoiceListResponse). Our API documentation has been following this new convention, which you will observe when setting the URL query parameter extended to true on list requests.

We recommend that you revise API client code to use extended=true and consume paged responses accordingly.

Classic list behavior is deprecated. Starting with the May 14 Socotra release, all list endpoint responses will be returned with the extended=true form, and the query parameter will no longer have a functional effect.

March 5, 2025

New Feature: First Notice of Loss

The First Notice of Loss (“FNOL”) feature allows you to capture key loss details before the formal claims process begins. See the FNOL Guide and API documentation for details.

New Feature Guides

February 26, 2025

Bug Fix

If a quote is created with a specific timezone and no explicit endTime, the quote’s timezone will be used as the basis for determining the endTime.

February 19, 2025

Rating Plugin Interface Update

The rating plugin interface has been updated so that rate or referenceRate do not need to be provided on RatingItems if an absolute amount is provided instead. See additional details in prior release notes.

Invoices API Update

Invoice records returned by the Invoices API list endpoints will no longer contain invoiceItems. An invoice and its invoiceItems will still be obtainable by fetching an invoice with its items.

Resource Selection Update

In plugins, you can now set a specific time for the resource selector to use as its reference point, like this:

Optional<VehicleTypeFactor> tableRecord = ResourceSelectorFactory.getInstance()
      .getSelector(Instant.now())
      .getTable(VehicleTypeFactor.class)
      .getRecord(VehicleTypeFactor.makeKey("toyota", "corolla", 2010));

Bug Fixes

Revised misleading error message on attempts to create users with invalid characters in the userName. The new error message clearly identifies the username as invalid, and why.
Updated quote validation to check whether an invalid timezone was provided.

February 12, 2025

Policy Transactions API Update

The Fetch Affected Transactions list of AffectedTransaction will no longer include reapplied transactions. Instead, the reapplicationOfLocator on the PolicyTransactionResponse will have the locator of the transaction being reapplied.

Jobs API Endpoint Deprecations

The Fetch Early Invoicing Job and Fetch Early Invoicing Jobs for Account endpoints are deprecated.

Bug Fix

The policy.quote.update event will now fire when adding, modifying, or deleting elements.

Forthcoming Changes

Invoices API: in next week’s release, invoice records returned by list endpoints will no longer contain invoiceItems. An invoice and its invoiceItems will still be obtainable by fetching an invoice with its items.
Plugin interface and list endpoint semantics update: see the January 22 release notes for details on impending changes to the rating plugin interface and list endpoint semantics throughout the Socotra API.

February 5, 2025

Account Constraints

You can now configure constraints for data extensions on accounts. See the Accounts API for details on corresponding constraint evaluation endpoints.

Documents API Update

Documents API fetch endpoints have a new suppressRenderingData option. When set to true, the API allows you to fetch 100 items per page instead of 10, but items will not include metadata or rendering data.

Forthcoming Plugin Interface Changes

See the January 22 release notes for details on impending changes to the rating plugin interface and list endpoint semantics throughout the Socotra API.

January 29, 2025

Internal changes only for this release.

See last week’s release notes for details on impending changes to the rating plugin interface and list endpoint semantics throughout the Socotra API.

January 22, 2025

Forthcoming Plugin Interface Changes

To facilitate upcoming support for flat charges and invoice fees, RatingItem objects returned from the rating plugin will no longer be required to have rate or referenceRate properties if an absolute amount is provided instead.

Existing plugin code that reads rate() or referenceRate() will need to recognize the returned values as Optional.

// code that is currently valid but will need to be updated after this change is deployed:
BigDecimal rate = ratingItem.rate();

// equivalent code after this change is deployed:
Optional<BigDecimal> rate = ratingItem.rate();

In the DocumentDataSnapshot plugin, the following properties will also become optional, and will need to be handled in a similar way:

InvoiceItemSummary.elementType
InvoiceItemSummary.elementStaticLocator
InvoiceItem.elementStaticLocator

The provisional release date for these changes is February 19.

We are analyzing deployed configurations to assess customer impact and ensure that configurations are updated for compatibility in coordination with this change rollout. Of course, deployment attempts after this change will fail with a compilation error if plugin code has not been updated to handle Optional types correctly.

Please contract your Socotra representative if you have any questions. We will provide additional updates about this impending change in subsequent release notes.

List Endpoint Semantics Update

As indicated in prior release notes (“Changes to Paged List Fetch Semantics”), Socotra is moving to a convention in which list results are not simply an array of items but an object containing the results array and an indicator listCompleted property to facilitate results pagination.

The new response format is documented for individual list endpoints (e.g. Fetch Multiple Accounts), and is obtained by setting the optional extended query parameter to true. Soon, all such endpoints will behave as though extended is true by default, and we will remove that query parameter and access to the original list response style.

We recommend that client code be updated to use extended=true in all list fetches so that response consumption is brought in line with the new standard. In upcoming release notes, we will provide a reminder and a date on which the extended=true response style will become the default.

January 15, 2025

Underwriting Event Payload Updates

The following underwriting event payloads will no longer include arrays of underwriting flags:

Underwriting flags on quotes and transactions can be fetched through the API, where they are exposed in QuoteUnderwritingFlagsResponse and TransactionUnderwritingResponse, respectively.

Other Changes

timezone has been added to QuoteUpdateRequest.
There is now a dedicated SAML identity provider creation endpoint and corresponding SAMLIdentityProviderCreateRequest.

January 8, 2025

New Feature: Availability

The availability feature facilitates the introduction and retirement of products, data extensions, policy elements, and coverage terms, supporting a variety of use cases. See the Availability Guide for details.

New Feature: Contact Management

Contact management brings the ability to define contacts and manage them in association with system entities. See the Contact Management Feature Guide for details.

New Static Data Endpoints

The following endpoints allow for fetching static data on quotes and policies, including historical values:

Underwriting Update

UnderwritingFlagCreateRequest and UnderwritingFlagResponse now have a tag property.

December 18, 2024

User Management API Update

An optional email property has been added to UserCreateRequest, UserUpdateRequest, and UserResponse.

Note

This is the final 2024 release. There will be no release on 2024-Dec-25, and no release the following week (2025-Jan-01). The next release will be available Wednesday, 2025-Jan-08.

December 11, 2024

Migration API update

The Migration API now allows you to specify Aux Data for importation with AuxDataMigrationRequest.

Identity Providers API update

IdentityProviderResponse now includes a callbackUrl property.

December 4, 2024

New Feature: Data Lake (Beta)

Data Lake provides a relational view of your book of business in Socotra, enabling a wide range of reporting applications. See the Data Lake Guide for details.

New Feature: Value-Based Coverage Terms

Until now, values to be associated with a coverage term had to be defined as a finite set of options in the configuration. To support use cases requiring variable values – such as a computed quantity based on various factors – a coverage term may now be configured to take a value described as a PropertyRef, instead of options. See the Coverage Terms Guide for details.

Other Changes

Use of the precommit plugin for delinquency events (method signature PreCommitDelinquencyEventsResponse preCommit(PreCommitPlugin.DelinquencyEventsRequest request)) is now deprecated.
Both “startsWith” and “fuzzy” searches are case-insensitive.

Bug Fixes

Pascal casing for account names is now enforced.
graceEndAt now accounts for gracePeriodDays if that value is set in the precommit plugin for delinquency, with graceEndAt taking precedence if it is also set in the plugin.
Deployments API: Validate Config and Format Config responses include a content-type: application/zip header.

November 20, 2024

New Feature: Early Invoicing

Early invoicing allows invoices to be created and sent before the generate time of the installments that they are based on.
See the Early Invoicing Feature Guide for details.

Note

There will be no release on 2024-Nov-27. The next release will be on 2024-Dec-04.

November 13, 2024

New Feature: Delinquency Events

Delinquency events are a new feature that supports extending delinquency processes with additional extensions.
For interacting with events directly, the Fetch Delinquency Events and Update Delinquency Event endpoints are added, along with responses DelinquencyEventsResponse and DelinquencyEventResponse
The endpoint Fetch Delinquency Event Jobs and response types DelinquencyEventJobDataListResponse and DelinquencyEventJobData have been added for job information.
See the Delinquency Events Feature Guide for details.

November 6, 2024

Constraint Tables

There is now an option to use any column (not just the first column) of a constraint table as a list of distinct values for constraints evaluation. Use of the first column is implicit if there is no where clause. To enable other columns, set the makeDistinct property in the column definition to true.
For consistency with other validation checks on configuration deployment, validation of constraint column names is now case sensitive as well. Column names in the constraints definition have to match case with column name in the associated constraint table definition.

Quote Events

Events have been added to signal changes to static data for quotes.
The new event types are policy.quote.staticdata.add, policy.quote.staticdata.replace, and policy.quote.staticdata.update, each of which emit a QuoteEventData object.

Optional Properties

The following properties are now marked as optional:

October 30, 2024

Constraints with Custom Data Types

Data extension constraints have been extended to include nested custom data objects. Constraining arrays of custom data objects is not yet supported.

Additional Changes to Paged List Fetch Semantics

The following endpoints have been updated to align with list endpoint semantics as described in recent release notes:

Get Migration Mappings returns AccountMigrationIdMappingsListResponse
List Account Migrations returns ListPageResponseAccountMigrationResponse
Get Migration Failures returns ListPageResponseMigrationFailuresResponse
Fetch Webhooks returns WebhookListResponse

Deployments

To better accommodate common zip file creation patterns on various systems, configuration deployment will no longer fail if the configuration archive contains an extra top-level directory.

October 23, 2024

Data Access Controls

Security features are now available to restrict users’ access to system data based on specific Products or Regions, or designated extension data.
See the Data Access Controls feature guide and Data Access Controls API guide for details.

Webhooks Security Features

Webhooks are now security enabled: The entities CreateEndpointRequest, UpdateEndpointRequest, and EndpointResponse have added properties secret, tag, secureSsl, and hmacEnabled.
See the Security Features section of the Webhooks configuration guide for implementation details.

Yet More Changes to Paged List Fetch Semantics

Similar to the endpoints that were enhanced last week, 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 Basic Users returns BasicUserListResponse (and, UserBasicResponse has been renamed to BasicUserResponse)
Fetch Tenants returns TenantListResponse
Fetch Invoices for Policy, Fetch Invoices for Account, Fetch Invoices for Quote, Fetch Invoices Targeted By a Credit Distribution and Fetch Invoices Targeted By a Payment return InvoiceListResponse
Fetch Installments for Policy, Fetch Installments for Policy Transaction, Fetch Installments for Quote return InstallmentListResponse
Fetch Installment Lattices By Policy Locator returns InstallmentLatticeListResponse
Fetch Multiple Payments and Fetch Payments for an Invoice return PaymentListResponse
Fetch Multiple Disbursements returns DisbursementListResponse
Fetch Multiple Credit Distributions and Fetch Credit Distributions for an Invoice return CreditDistributionListResponse
Get Delinquencies for Account, Get Delinquencies for Quote, Get Delinquencies for Policy and Get Delinquencies for Invoice return DelinquencyListResponse
Fetch Credits and Fetch Credits for an Invoice return CreditListResponse
Fetch Multiple Shortfall Credits returns ShortfallCreditListResponse
Fetch Multiple Write Offs returns WriteOffListResponse
Fetch All Holds for an Account returns HoldListResponse
List Financial Instruments returns FinancialInstrumentListResponse
Fetch Multiple Ledger Cash Accounts returns LedgerAccountListResponse
Fetch Installments Job Data for Transactions, Fetch Installments Job Data for Quotes return InstallmentJobDataListResponse
Fetch Delinquency Grace Job returns GraceJobDataListResponse
Fetch Create Delinquencies Job Data for Invoice returns DelinquencyCreateJobDataListResponse

The Open API descriptor file and documentation for endpoints expresses these responses as if the extended property were set to true.

Note

Later, the extended property will be deprecated, and then removed and the default behavior will be as if it were true. Until then, the default value for this flag is false.

Other Changes

There is a new Feature Guide for Dynamic Documents!
There is a new block of example code provided for the Document Data Snapshot Plugin configuration guide.
The InvoiceItemResponse entity has new property invoiceItemLocators.
The InvoiceItemPreview entity has new optional properties policyLocator, quoteLocator, chargeCategory, chargeType, and transactionLocators.

October 16, 2024

Entity Numbering

Several system entities, including accounts, policies, quotes, policy terms, invoices, and disbursements can now have automatically generated numbers, for use on printed documents, portal and app screens, etc.
This provides a much easier, human-readable identifier compared to locators.
Numbers are ideal for use in customer service and similar situations.
See the Entity Numbering Feature Guide for details.

More 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 My Tenants returns TenantListResponse
Fetch Documents for Transaction, Fetch Documents for Segment, and Fetch Documents for Quote return DocumentListResponse
Fetch Multiple Documents Jobs for Transaction, Fetch Multiple Documents Jobs for Segment, and Fetch Multiple Documents Jobs for Quote return DocumentJobListResponse
Fetch Multiple Users returns UserListResponse.
Fetch Multiple Roles returns RoleListResponse.
Fetch Multiple Resources returns ResourceListResponse
Fetch Resource Groups returns ResourceGroupListResponse

Other Changes

The InvoiceItemPreview entity has added fields policyLocator, quoteLocator, chargeCategory, chargeType, and transactionLocators properties.
The InvoiceItemResponse entity has new property transactionLocators.
The DeployedConfigMetadata entity’s pluginVersionStatus has type changed from map<string,string> to map<string,map<string,string>>.

October 9, 2024

New Feature Guides

Other Changes

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

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 Document Management 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.

Older Changes

See the release notes archive for older release notes.