Our StoryBlogPodcastAdoption Report
Updates
Activate Account
Start typing to search…

February 2026

Introduction

Today, we are releasing the February 2026 update to our API, as well as version 3.0.0 of our Backend SDKs. This update focuses on improving the structure of the API to reduce confusion and inconsistencies and improve functionality.

Most of the changes described today are compile-breaking changes, meaning that upgrading to a 3.0.0 SDK will introduce compilation errors in existing implementations. The necessary code changes should be relatively simple, however. Our intent with this update is to significantly reduce the number of breaking changes made in the future.

Finally, as part of our continuous work to improve platform internals, we are switching to a new, semantic identifier format for Verification Profile IDs. Most Verification Profiles have been given a new ID in a backwards-compatible manner; see below for more details.

Table of Contents

Non-Breaking Changes

The following are changes which solely add new functionality and will not break compilation when upgrading to a 3.0.0 SDK.


New document.issuingSubdivision field

The DocumentData model now contains an issuingSubdivision field, which contains the ISO 3166-2 country-subdivision code of the issuing authority; eg, US-TX for United States, Texas.


Breaking Changes

📘

On Breaking Changes

All of the breaking changes and deprecations described below have no impact on existing integrations using SDKs below version 3.0.0.

All changes are backwards-compatible for 90 days:

  • Deprecated API endpoints will continue to serve requests in the same way
  • Deprecated fields or models will continue to be returned by the API
    • Renamed fields will continue to output both the old and new field names
  • Major changes in endpoint behavior have been implemented by introducing new endpoints; the behavior of existing endpoints has not changed.

The following are changes which take effect today and which may break your compilation when upgrading to an SDK of version 3.0.0 or higher.

All 90-day timelines mentioned below will take effect on May 3, 2026 (90 days after publication of this document). After this date, deprecated endpoints, data models, and fields will be removed from our API surface.


Verification Profile IDs Changed

Note: this change is not "breaking" in that it requires no immediate code changes to upgrade to a 3.0.0 SDK.

All Verification Profiles created before January 6, 2026 have been given a new ID. Verification Profiles created after January 6 already use the new ID format, and have not had their IDs changed.

The previous ID for a Verification Profile will continue to function when passed to the API or searched for in the Trinsic Dashboard for at least 90 days. No immediate changes are necessary.

This change is being made as part of our continual work to improve platform internals and support scalability. Previously, IDs for Verification Profiles were random GUIDs; with this change, all resources in our platform now use a standardized, semantic ID format.

An example of a Verification Profile ID in the old format is b7868d01-df21-4b44-ae40-1308650d0f4e.

An example of a Verification Profile ID in the new format is 66e68622-f0c3-804a-a4cb-000b923bae5e.

Relevant If:

  • Relevant to all users of Trinsic's API

Change Necessary:

  • Update any internal references to Verification Profile IDs in your source code, configuration, or documentation to point to their new IDs.
    • Tip: using the Trinsic Dashboard, pasting either a new or old Verification Profile ID into the search bar will properly display the expected Profile; this can be used to aid migration efforts.
    • Alternatively, our team can provide you with a simple list mapping all previous IDs to the new IDs upon request.
  • A quick way to discern between "old" and "new" formats of Verification Profile IDs is to look at the first digit of the third section; IE: xxxxxxxx-xxxx-Axxxx-xxxxxxxxxxxx.
    • If the value of A is 4, the ID is in the old format.
    • If the value of A is 8, the ID is in the new format.

New Attachment API

We have redesigned how Attachments work, with the goal of reducing confusion and improving the usefulness of this API.


Deprecation of attachmentAccessKeys in favor of attachments

The attachmentAccessKeys field in the normalized data model has been deprecated in favor of a new attachments field. The concept of an attachmentAccessKey is also being deprecated.

This new output is designed to be less confusing, more flexible, and more useful.

"attachmentAccessKeys": {
  "selfie": "Btmibt4{....}B8utZP-dPf7w",
  "documentPortrait": "Bn6zptUx3wYPs{....}9hcqA-7aZmQ",
},
"attachments": [
  {
      "id": "6702cc1b-ff04-804b-92cd-3da9a953296e",
      "type": "selfie",
      "contentType": "image/png",
      "sizeBytes": 27155
  },
  {
      "id": "6702cc1b-ff04-80b7-923d-0e9b0cf3f859",
      "type": "document_portrait",
      "contentType": "image/png",
      "sizeBytes": 27155
  }
],

Relevant If:

  • You make use of the Attachments feature

Changes Necessary:

  • Read from attachments instead of attachmentAccessKeys when processing Session results
    • See the documentation for the type field for all possible values of this field.
  • Switch to the new API endpoint for fetching Attachments (see below)

New GetAttachment endpoint

The previous GetAttachment endpoint, which took an attachmentAccessKey, has been deprecated.

A new GetAttachment endpoint, which takes a sessionId, resultsAccessKey, and an attachmentId, has been added. The output of this new endpoint is the same as the now-deprecated endpoint.

Relevant If:

  • You make use of the Attachments feature

Changes Necessary:

  • Switch to the new GetAttachment Endpoint
    • If using an SDK, this new Endpoint will be located under the Sessions category, instead of under the (now-deprecated) Attachments category.
    • If not using an SDK, you will need to manually update the path of this endpoint in your implementation.
      • Old path: POST /api/v1/attachments/attachment
      • New path: POST /api/v1/sessions/{sessionId}/attachments/{attachmentId}/get

Deprecation of Redirect URL Query Parameters

Deprecation of resultsAccessKey query parameter

The resultsAccessKey query parameter, appended to Redirect URLs by Trinsic when sending a user back to your application, is now deprecated and will no longer be included in 90 days.

Instead, use the resultsAccessKey provided by Trinsic in response to a Create Session API endpoint, saving it securely in your backend.

Relevant If:

  • You rely on the resultsAccessKey query parameter on redirect
    • Relying on the resultsAccessKey returned by a Create Session endpoint does not qualify

Changes Necessary:

  • Rely on the resultsAccessKey returned by Trinsic in response to CreateWidgetSession, CreateHostedSession, or CreateDirectSession.
    • Each endpoint returns a resultsAccessKey, which should be saved securely in your backend and used later to fetch Session results.
    • Do not use the resultsAccessKey present in user query parameters, as it will cease to exist in 90 days.

Deprecation of success query parameter

The success query parameter, appended to Redirect URLs by Trinsic when sending a user back to your application, is now deprecated and will no longer be included in 90 days.

This query parameter ultimately serves little use and encourages unsafe usage of untrusted query parameters for core workflow decisions. We intend to introduce significantly improved error handling in the future which will address the use cases that the success parameter intended to.


Relevant If:

  • You rely on the success query parameter on redirect

Changes Necessary:

Region / Geography Changes

Deprecation of the United States region

The use of United States in a region returned by ListProviderContracts has been deprecated in favor of the North America region.

For 90 days, United States will continue to be included in the list next to North America.

{
  "id": "...",
  "regions": ["United States"],
}
{
    "id": "...",
    "regions": ["North America", "United States"], //"United States" only present for 90 days
    "countries": ["US"],
}

Relevant If:

  • You use the ListProviderContracts endpoint and make use of the returned region information

Changes Required:

  • Use North America instead of United States in any hardcoded regions in your source code or configuration
    • You may wish to additionally inspect the countries array for the presence of the string "US"

Deprecation of geography in favor of countries and subdivisions

The geography field on Providers returned by ListProviderContracts has been deprecated in favor of the countries and subdivisions fields:

{
  "id": "...",
  "regions": ["United States"],
  "geography": ["CA"],
}
{
    "id": "...",
    "regions": ["North America", "United States"], //"United States" only present for 90 days
    "countries": ["US"],
    "subdivisions": ["US-CA"],
}

Relevant If:

  • You use the ListProviderContracts endpoint and make use of the returned geography information

Changes Required:

  • Use countries and subdivisions instead of geography when interpreting Provider Contracts

Deprecation of Network API Category

📘

On the Term "Provider Contract"

The term "Provider Contract" or "Contract" in this document refers to the output of the ListProviderContracts (now ListProviders) endpoint; that is, the technical contract for the Provider's behavior within Trinsic's platform. It does not refer to a legal contract.

ListProviders and ListProviderContracts merged into new ListProviders endpoint

The ListProviders and ListProviderContractsendpoints within the now-deprecated Network category have had their functionality merged into a new ListProviders endpoint in a new Providers category.

Relevant if:

  • You call the ListProviders or ListProviderContracts endpoints

Changes Required:

  • Use new ListProviders endpoint
    • If using an SDK, this new Endpoint is located under the Providers category.
    • If not using an SDK, you will need to manually update the path of this endpoint in your implementation.
      • Old path: GET /api/v1/network/{verificationProfileId}/providers
      • New path: GET /api/v1/providers
  • Use ListProviders instead of ListProviderContracts

RecommendProviders reworked and moved to Sessions API Category

The RecommendProviders endpoint within the now-deprecated Network category has been moved to the Sessions category; its path has been updated accordingly.

The output of the new endpoint has also changed:

  • recognized and remainder are no longer returned; only relevant Providers are emitted by this API.
    • Note: calling the RecommendProviders endpoint without any parameters will result in relevant being populated by all possible Providers available to your Verification Profile, which offers the same functionality as remainder.

Relevant If:

  • You use the RecommendProviders endpoint

Changes Required:

  • Switch to the new RecommendProviders Endpoint
    • If using an SDK, this new Endpoint is located under the Sessions category, instead of under the deprecated Network category.
    • If not using an SDK, you will need to manually update the path of this endpoint in your implementation.
      • Old path: POST /api/v1/network/recommend
      • New path: POST /api/v1/sessions/providers/recommend
  • If your integration relies upon the now-deprecated remainder set of Providers, call RecommendProviders without any parameters to replicate this functionality

Provider Contract Model Changes

The new ListProviders endpoint, which now includes Provider Contract information, brings with it a few field/model renames:

  • The availableFields field on the Provider model has been renamed to availableAttributes
  • The description field on the Provider model has been renamed to subtext
  • The ContractField model has been renamed to ContractAttribute
    • The name field on the ContractAttribute model has been renamed to scope
  • The FieldAvailability enum has been renamed to AttributeAvailability

These have all been renamed to increase consistency of language across the platform and to better represent their nature.


Relevant If:

  • You call the ListProviderContracts (now ListProviders) endpoint

Changes Required:

  • Read from availableAttributes instead of availableFields
  • Read from subtext instead of description
  • Read from ContractAttribute.scope instead of ContractAttribute.name
  • Use the AttributeAvailability enum instead of FieldAvailability

Deprecation of Identifiers

Note: this feature was experimental and not officially released; this section will not apply to most integrations.

The experimental Identifiers field in our normalized data model has been deprecated.

This feature was intended to address customer need for data beyond the normalized model; we have decided to enable these use cases in alternative ways, such as rich Provider-Specific output models and evolutions of our normalized data model.

Relevant If:

  • You read the Identifiers field on the normalized data model

Changes Required:

  • Use ProviderOutput instead of Identifiers

Provider Input & Output Field Names Standardized

The JSON field names of the ProviderInput and ProviderOutput models have been standardized to always use Provider IDs (e.g., italy-spid) as JSON field names.

Relevant if:

  • You make use of the ProviderInput field when creating Hosted or Direct Sessions
  • OR
  • You interpret the (beta) ProviderOutput field when reading Session results

Changes Required:

  • If using an SDK, modify any manual references to fields on these models
    • Any changed field names will appear as a compilation error when upgrading to a 3.0.0 SDK, which should make migration a relatively simple effort.
  • If not using an SDK, modify your source code to read and/or write to the new standardized field names.

Providers

California DMV: Deprecation of FullName and FullAddress

The California DMV Wallet Provider (usa-california-dmv) currently returns a value for the FullName and FullAddress fields in the normalized data model.

These fields were not actually returned by the underlying Provider, and instead were being synthesized by Trinsic's platform from the constituent parts (eg, GivenName, FamilyName). This behavior was unique to this Provider; the platform was not performing this synthesis for any other Provider.

The Trinsic API will stop populating the FullName and FullAddress fields in 90 days.

Relevant If:

  • You use the California DMV Wallet (usa-california-dmv) Provider and make use of the FullName or FullAddress fields

Changes Required:

  • Use the constituent returned data components for this Provider
    • EG, GivenName and FamilyName instead of FullName

SmartID and MobileID: Nationality Deprecated

The Nationality field in the normalized data model is now deprecated for the SmartID and MobileID Providers, and will no longer be emitted in 90 days. The presence of this field was an error, as nationality information is not provided by these Providers.

Instead, use the IssuingCountry field on the DocumentData model, assuming this fits your purposes.

Note: The Nationality field itself is not being deprecated; only its presence for these specific Providers.

Relevant If:

  • You use the SmartID (smart-id) or MobileID (mobile-id) Providers and make use of the PersonData.Nationality field

Changes Required:

  • Stop reading from PersonData.Nationality when using these Providers, as it will no longer be present in 90 days.
  • Switch to DocumentData.IssuingCountry if appropriate for your use-case.

Yoti: Improved Direct Mode Support

The yoti Provider has been updated to support improved Direct integrations and UX.

Because this changes the behavior of the Provider in Direct mode, the new functionality is available in a new yoti-deeplink Provider.

The existing yoti Provider will continue to function as before for 90 days, after which time it will function the same as yoti-deeplink.

Relevant If:

  • You use the yoti Provider in Direct mode

Changes Required:

  • Switch to the yoti-deeplink Provider
    • You will need the DeeplinkToMobile and PollResult capabilities when using the Direct API.
  • If you use Hosted or Widget mode, you do not need to make any changes.



October 2025

To better facilitate the management of a large number of customer and end-provider configurations, the Trinsic platform has migrated from "Apps" to "Verification Profiles".

Verification Profiles & Environments

  1. Apps have been renamed to Verification Profiles.
  2. Your organization now has two environments -- Live and Test -- which can be switched between in the Dashboard. Verification Profiles reside within environments.
  3. [BREAKING] Auth Tokens are now organization-level and are tied to an Environment rather than a specific App / Verification Profile.
    1. App-specific Auth Tokens are now called "Legacy Tokens" and will stop functioning after 90 days.
  4. [BREAKING] Some API endpoints now require a verificationProfileId parameter.
    1. Previously, these API endpoints were called with Auth Tokens tied to a specific App / Verification Profile ID. These Auth Tokens are now Legacy.
    2. Existing integrations will continue to function for 90 days.
  5. Providers must now be explicitly "added" to Verification Profiles, during or after creation.
    1. If a Provider has no required approval or registration process, it will be immediately available for use.
    2. If a Provider requires approval and/or a registration process, the Provider will be added to the Verification Profile in a disabled, unapproved state.
      1. Once the necessary approvals / registrations are performed by Trinsic, the Provider will appear as "Approved" for your Verification Profile.
    3. Once added to a Verification Profile, a Provider can be enabled or disabled indepenently.
  6. Redirect URLs are now tied to Environments as opposed to individual Apps / Verification Profiles.
  7. User management has been improved
    1. As before, users within an organization may be a "Member" or an "Admin."
      1. Admins may access all environments and modify the roles of other users within the organization.
      2. Members may only access environments they are given access to, and cannot modify other users' roles.
    2. Access to Apps / Verification Profiles is now determined by the environments a user has access to
      1. By default, a user with the role of "Member" may only access the Test environment within an organization.

Other breaking changes

  1. The Advanced API has been renamed; it is now the Direct API.
    1. No functionality has changed, but an SDK update is required in order to hit the correct new routes for these API endpoints.
    2. Existing integrations will continue to function for 90 days.
  2. Our Web UI SDK has been updated to version 3.0.0
    1. This SDK has been restructured to provide a higher level of control over the user experience and popup management, if needed for your integration.
    2. Complexities around certain browser security restrictions (e.g. Cross-Origin-Opener-Policy), which can cause issues with cross-window communication as required by this SDK, are addressed by this update.
  3. For the endpoints Submit Native Challenge Response and Refresh Step Content, the acceptanceSessionId parameter has been renamed to sessionId.

Other changes

  1. Trinsic's internal "Test" providers (e.g., "Test - Redirect") have been renamed to "Mock" providers.
    1. This is a cosmetic change only

Upcoming Changes

  1. The base domain name for Trinsic's user-facing endpoints will soon change
    1. User redirects (including launchUrl), as well as Trinsic's Widget and Hosted UIs, will be served from verify.trinsic.id.
    2. The domain name of the Trinsic API (api.trinsic.id) will remain the same.
    3. No changes to your integration are necessary to support this change.


Migration Guide

ℹ️

Deprecation Timeline

No immediate changes are necessary to retain existing functionality with your Trinsic integration.

All changes described in this document are fully backwards-compatible for 90 days from the posting of this notice.

Auth Tokens & verificationProfileId Parameter

Relevant to: all integrations

Existing Auth Tokens, which are scoped to specific Verification Profiles (previously "Apps"), are now considered Legacy Tokens. These Tokens will cease functioning 90 days after the posting of this document.

Auth Tokens are now scoped to your organization and environment, as opposed to individual Verification Profiles within an environment. A token for the test environment may create Sessions for any Verification Profile in that environment.

Because Organization Tokens are not tied to specific Verification Profiles, a newverificationProfileId parameter is required when calling the following endpoints with an Organization Token:


Changes Required

  1. Replace your Legacy Tokens with Organization Tokens
    1. Your Organization Tokens can be found on the Developer page of the Trinsic Dashboard.
    2. Store the new Organization Token for each environment in your secret storage system.
  2. Update your Backend SDK
    1. Organization Tokens require the newest version of Trinsic's backend SDKs
    2. If you are not using a backend SDK, you will need to update your implementation against our API reference for the affected endpoints.
      1. Specifically, you must include the verificationProfileId parameter in either the route or request body for each endpoint.
  3. Specify verificationProfileId in affected API calls
    1. Since tokens are no longer tied to specific Verification Profiles, you must specify the verificationProfileId you wish to use in the above-listed API calls.


Renaming of Create Advanced Provider Session Endpoint

Relevant to: integrations which call this endpoint

This endpoint has been renamed to Create Direct Provider Session to better reflect its nature. No other changes have been made besides the addition of the verificationProfileId parameter as part of the auth token changes.


Changes Required

  1. Update your Backend SDK
    1. The new endpoint names and paths will automatically be included with the latest version of our SDK.
    2. If you are not using a Trinsic SDK, you will need to update your integration to call the new route of the endpoint. See reference.


Web UI SDK v3.0.0

Relevant to: integrations which use the Trinsic Web UI SDK to launch popups vialaunchPopup

Our Web UI SDK has been updated to v3.0.0. This introduces a compile-time breaking change with the removal of the launchPopup method. Additionally, we have reworked the cross-window communication mechanisms and included a related helper function.


⚠️ Note on iFrames

If you are launching a Trinsic popup from within an iFrame, there are additional complexities to be aware of due to various browser security mechanisms.

This SDK update includes improved support for iFrames, but brings with it additional requirements. Please read the Web UI SDK Documentation to better understand the requirements of launching from an iFrame.


resultsAccessKey No Longer Returned

Previously, this library would return a resultsAccessKey to your frontend after the popup session resolved. This has been removed. Instead, use the resultsAccessKey provided to your backend during Session creation.

This change has been implemented to ensure that the resultsAccessKey for a Session is saved securely in your backend context.


Redirect Handling

When calling launchPopup with Create Hosted Provider Session or Create Direct Provider Session], you previously had to implement custom cross-window messaging to signal completion of a Session (or implement polling). Our SDK now provides this out of the box.

As before, create a Hosted Provider Session with a redirectUrl pointing to a page you control. When the user lands on this page, pull out the sessionId from the query parameters and signal completion to the window which opened the popup:

import { signalRedirectFromPopup } from "@trinsic/web-ui";

const urlParams = new URLSearchParams(window.location.search);
const sessionId = urlParams.get("sessionId");

// Signal to the window which opened this popup that the Session is done
signalRedirectFromPopup(
  {
    sessionId: sessionId,
    closeWindowAfterSignal: true
  }
);

launchPopup() -> createPopupAndWaitForResults()

For the simplest migration, use the included helper function createPopupAndWaitForResults(), which has a similar API surface to the previous launchPopup method:

import { createPopupAndWaitForResults } from "@trinsic/web-ui";

// Create a popup, initialize it with a launch URL, and wait for it to signal completion
const result = await createPopupAndWaitForResults({
  // A callback function which should call your backend to create a Trinsic Session,
  // and return the Launch URL.
  //
  // This pattern is necessary due to browser restrictions around opening a popup too late
  // after a user gesture (e.g. button click).
  sessionCreationFunction: async () => {
    // Hit your backend to create a Trinsic Session and return its launch URL
    return await createTrinsicSessionLaunchUrl();
  },
});

// Notify your backend of Session completion
const sessionId = result.sessionId;
await notifyBackend(sessionId);
// Previous implementation
import { launchPopup } from "@trinsic/web-ui";

// Call `launchPopup()`, passing a callback to asynchronously create a Session URL
// `launchPopup()` resolves when it receives a completion signal from the popup, or on error
const result = await launchPopup(async () => {
  // Hit backend to create a Trinsic Session and return its launch URL
	return await createTrinsicSessionLaunchUrl();
});

// Notify your backend of Session completion
const sessionId = result.sessionId;
await notifyBackend(sessionId);

Optional: createPopup() API

For more direct control over the popup management process, including the ability to respond to the possible closure of the popup with custom logic or close the popup at will, use the new createPopup() API.

Please see the Web UI SDK Documentation for a usage example.

July 2025

Breaking Changes

All changes below are backwards compatible until the end of the notice period. Legacy SDKs and integrations will continue functioning as expected during this time. For renamed properties we will still output the previous names on the API endpoints. We’re happy to support your migration efforts via pair programming or dedicated meetings — feel free to reach out.

Delayed results on redirect

Delayed Result Handling: Advanced Sessions can now explicitly handle situations when results are not yet available during a redirect (e.g., due to pending webhooks or provider-side processing delays). Use the List Provider Contracts or Provider Capabilities pages to check for which providers this applies. Read more on Advanced Provider Session

Hosted Session Improvement: Our hosted session implementation now automatically waits for results to be available before completing the session flow.

Widget Session iFrame Launch Removed
Support for launching Widget Sessions inside an iFrame has been removed due to security issues with third-party cookie restrictions and provider compatibility. Use popup or redirect flows instead.

Provider ID Standardization
Provider identifiers (providerId) have been standardized. Updated IDs are available in the dashboard and APIs. Existing (legacy) IDs will continue to function for Hosted and Advanced session creation until the end of the notice period.

Hosted Session Input Removed
The input property for Hosted Sessions is now obsolete. This change eliminates confusion where lookup providers were already ready before launching, but a browser session still launched unnecessarily. For partial form entry or step-based logic, use the Advanced Sessions API, which offers similar capabilities with greater control.

API Field Renames

Affected APIOld FieldNew Field
List Providersdescriptionsubtext
List Provider Contractsdescriptionsubtext
Recommend ProvidersproviderIdid
providerDisplayNamename
providerLogologoUrl

Other Notable Changes

Immutable Test Mode

You must now explicitly set your app to either test or live mode via the dashboard. At the end of the notice period, your current setting will be locked in automatically.

Mobile handover

When using hosted sessions we will now hand the user over to their mobile phone when appropriate, similar as widget sessions did before. This ensures that camera that needs to be captured is of high quality and improves pass rates. For the Advanced Session API when fallbackToTrinsicUI is enabled it will also prompt this handover.

New API Properties