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
Invoices API: in next week’s release, invoice records returned by list endpoints will no longer contain
invoiceItems
. An invoice and itsinvoiceItems
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 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 forgracePeriodDays
if that value is set in the pre-commit plugin for delinquency, withgraceEndAt
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 themakeDistinct
property in the column definition totrue
.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
, andpolicy.quote.staticdata.update
, each of which emit a QuoteEventData object.
Optional Properties
The following properties are now marked as optional:
PaymentRef and PaymentResponse:
data
CreateEndpointRequest:
headers
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
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
, andhmacEnabled
.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
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
, andtransactionLocators
.
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.
Other Changes
The InvoiceItemPreview entity has added fields
policyLocator
,quoteLocator
,chargeCategory
,chargeType
, andtransactionLocators
properties.The InvoiceItemResponse entity has new property
transactionLocators
.The DeployedConfigMetadata entity’s
pluginVersionStatus
has type changed frommap<string,string>
tomap<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 beproduct
,policyLine
,exposureGroup
,exposure
, orcoverage
.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. Iftrue
, then the transaction will revert to draft state and the generated segment data, including elements and data, will be discarded. Iffalse
(the default), then the transaction will revert toinitialized
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.