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.

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

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

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

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 pre-commit 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 pre-commit 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

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:

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

Webhooks Security Features

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:

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

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:

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

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!

New Migration Feature Guide

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

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

Older Changes

See the release notes archive for older release notes.