v1

latestOpenAPI 3.0.42026-07-2419101123.9 KB

Sessions

Create Direct Provider Session

Verify a user's identity with a specific provider, handling additional user interaction in your own UI.

Signal which kinds of user interactions your UI can handle using the Capabilities field.

If FallbackToHostedUi is true, Trinsic's hosted UI will automatically be invoked to handle any capabilities you do not support.

post/api/v1/sessions/provider/direct

Request body

providerstring required

The ID of the provider to launch

verificationProfileIdstring uuid required

The ID of the Verification Profile to use for this session.

redirectUrlstring nullable

The Redirect URL to which the user should be sent after the session is complete.

This field is required for providers which employ a redirect-based flow.

capabilitiesIntegrationCapability[] required

The list of capabilities your integration supports. Capabilities are the core of Trinsic's whitelabel-with-optional-fallback offering.

Most capabilities align with either an IntegrationLaunchMethod or an IntegrationCollectionMethod. The exception being refresh content to support updating the content of the launch method.

For example, to support a basic redirect-based flow, you must include the LaunchRedirect and CaptureRedirect capabilities. To support a mobile deeplink / polling flow, you must include the DeeplinkToMobile and PollForResults capabilities.

If FallbackToHostedUi is true, Trinsic will automatically fall back to a Trinsic-hosted UI to cover any gaps in your integration's capabilities. If FallbackToHostedUi is false, gaps in your integration's capabilities will result in an error during Session creation.

Read more on how to integrate at <a href="https://docs.trinsic.id/docs/direct-provider-sessions">the guide on Direct Provider Sessions</a>

fallbackToHostedUIboolean nullable

Whether the session should fall back to a Trinsic-hosted UI in certain instances.

Specifically, fallback will occur if any of the following are true:

You attempted to launch a provider which requires a capability you did not express support for
- In this case, Trinsic's hosted UI will perform the necessary capability
You attempted to launch a provider which requires input, and the input was either not provided or incomplete
- In this case, Trinsic's hosted UI will collect the necessary input from the user

If fallback occurs, the session's NextStep will always be LaunchBrowser, and the CollectionMethod will always be CaptureRedirect.

If this field is set to true, you must also:

Set the RedirectUrl field to a non-empty value
Include the LaunchBrowser and CaptureRedirect capabilities in the Capabilities field

browserLanguagesstring[] nullable

Preferences for languages to show first in supported provider launch flows and, if the session falls back, in the Trinsic-hosted UI. If left empty, the Hosted UI defaults to the user's navigator languages. If no preferred language is available, the Hosted UI falls back to English.

Example request

{
  "providerInput": {
    "google-wallet": {
      "preview_raw18013Request": {
        "documentRequests": [
          {
            "documentType": "org.iso.18013.5.1.mDL",
            "nameSpaces": {
              "org.iso.18013.5.1": {
                "given_name": true,
                "family_name": true,
                "portrait": false
              },
              "org.iso.18013.5.1.aamva": {
                "name_suffix": true
              }
            }
          }
        ]
      }
    },
    "apple-wallet": {
      "preview_raw18013Request": {
        "documentRequests": [
          {
            "documentType": "org.iso.18013.5.1.mDL",
            "nameSpaces": {
              "org.iso.18013.5.1": {
                "given_name": true,
                "family_name": true,
                "portrait": false
              },
              "org.iso.18013.5.1.aamva": {
                "name_suffix": true
              }
            }
          }
        ]
      }
    },
    "samsung-wallet": {
      "preview_raw18013Request": {
        "documentRequests": [
          {
            "documentType": "org.iso.18013.5.1.mDL",
            "nameSpaces": {
              "org.iso.18013.5.1": {
                "given_name": true,
                "family_name": true,
                "portrait": false
              },
              "org.iso.18013.5.1.aamva": {
                "name_suffix": true
              }
            }
          }
        ]
      }
    },
    "france-identite": {
      "preview_raw18013Request": {
        "documentRequests": [
          {
            "documentType": "org.iso.18013.5.1.mDL",
            "nameSpaces": {
              "org.iso.18013.5.1": {
                "given_name": true,
                "family_name": true,
                "portrait": false
              },
              "org.iso.18013.5.1.aamva": {
                "name_suffix": true
              }
            }
          }
        ]
      }
    },
    "poland-mobywatel-match": {
      "givenName": "Jan",
      "familyName": "Kowalski",
      "dateOfBirth": "1980-10-20",
      "nationality": "PL",
      "personalNumber": "80102005992",
      "expirationDate": "2030-12-31"
    },
    "bolivia-ci-lookup": {
      "documentNumber": "123456789",
      "dateOfBirth": "1990-03-15"
    },
    "colombia-cc-lookup": {
      "documentNumber": "1234567890",
      "issueDate": "2025-10-31"
    },
    "el-salvador-dui-lookup": {
      "documentNumber": "123456789",
      "dateOfBirth": "1995-12-01"
    },
    "guatemala-cui-lookup": {
      "documentNumber": "1234567890101"
    },
    "panama-cedula-lookup": {
      "documentNumber": "8-1234-12345",
      "dateOfBirth": "1992-03-02"
    },
    "peru-dni-lookup": {
      "documentNumber": "19050215"
    },
    "uk-evisa-lookup": {
      "shareCode": "R9Z3X7K2P"
    },
    "usa-california-dmv": {
      "preview_raw18013Request": {
        "documentRequests": [
          {
            "documentType": "org.iso.18013.5.1.mDL",
            "nameSpaces": {
              "org.iso.18013.5.1": {
                "given_name": true,
                "family_name": true,
                "portrait": false
              },
              "org.iso.18013.5.1.aamva": {
                "name_suffix": true
              }
            }
          }
        ]
      }
    }
  }
}

Response

sessionIdstring uuid required

The ID of the newly-created Acceptance Session

Example response

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "resultCollection": {
    "resultsAccessKey": "417zNGHMJp6Ht2jCoktTLNGDRZEt4BqTwwQ8Q9ZaQz8aS4Jd7nD1xff2WLhPS69j5q9QT4gvgV79Gv7QtaXwu5YC9Utr35..."
  },
  "nextStep": {
    "content": "https://verify.trinsic.id/api/session/launch?clientToken=..."
  }
}