# 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](#verification-profile-ids-changed) for more details. *** # Table of Contents * **Non-Breaking Changes** * [New `document.issuingSubdivision` field](#new-documentissuingsubdivision-field) * **Breaking Changes** * [Verification Profile IDs Changed](#verification-profile-ids-changed) * **New Attachment API** * [Deprecation of `attachmentAccessKeys` in favor of `attachments`](#deprecation-of-attachmentaccesskeys-in-favor-of-attachments) * [New `GetAttachment` endpoint](#new-getattachment-endpoint) * [Deprecation of Redirect URL Query Parameters](#deprecation-of-redirect-url-query-parameters) * [Deprecation of `resultsAccessKey` query parameter](#deprecation-of-resultsaccesskey-query-parameter) * [Deprecation of `success` query parameter](#deprecation-of-success-query-parameter) * **Region / Geography Changes** * [Deprecation of the `United States` region](#deprecation-of-the-united-states-region) * [Deprecation of `geography` in favor of `countries` and `subdivisions`](#deprecation-of-geography-in-favor-of-countries-and-subdivisions) * **Deprecation of `Network` API Category** * [`ListProviders` and `ListProviderContracts` merged into new `ListProviders` endpoint](#listproviders-and-listprovidercontracts-merged-into-new-listproviders-endpoint) * [`RecommendProviders` reworked and moved to `Sessions` API Category](#recommendproviders-reworked-and-moved-to-sessions-api-category) * [Provider Contract Model Changes](#provider-contract-model-changes) * [Deprecation of `Identifiers`](#deprecation-of-identifiers) * [Provider Input & Output Field Names Standardized](#provider-input--output-field-names-standardized) * **Providers** * [California DMV: Deprecation of `FullName` and `FullAddress`](#california-dmv-deprecation-of-fullname-and-fulladdress) * [SmartID and MobileID: `Nationality` Deprecated](#smartid-and-mobileid-nationality-deprecated) * [Yoti: Improved Direct Mode Support](#yoti-improved-direct-mode-support) *** # 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. ```json Previous "attachmentAccessKeys": { "selfie": "Btmibt4{....}B8utZP-dPf7w", "documentPortrait": "Bn6zptUx3wYPs{....}9hcqA-7aZmQ", }, ``` ```json New "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](https://docs.trinsic.id/reference/getattachment) 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](https://docs.trinsic.id/reference/getattachment) * **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**: * Rely on the result of the [`GetSessionResult` endpoint](https://docs.trinsic.id/reference/getsessionresult) instead of the `success` query parameter *** ## 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`. ```json Previous { "id": "...", "regions": ["United States"], } ``` ```json New { "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: ```json Previous { "id": "...", "regions": ["United States"], "geography": ["CA"], } ``` ```json New { "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 `ListProviderContracts`endpoints 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](https://docs.trinsic.id/reference/listproviders) * **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](https://docs.trinsic.id/reference/recommendproviders) * **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.