---
title: "Recommend Providers"
method: POST
path: "/api/v1/sessions/providers/recommend"
tags: ["Sessions"]
---

# Recommend Providers

`POST /api/v1/sessions/providers/recommend`

Recommend providers for a specific user session.
You can filter based on health (default=online) and specify country and subdivision information.
Trinsic will use the phone number and IP address, if provided, to deduce the country and subdivision of the user and use that info for filtering the providers.

## Request body

- RecommendProvidersRequest
  - `verificationProfileId` string, uuid, required — The ID of the VerificationProfile to use for this recommendation.
  - `recommendationInfo` RecommendationInfo — Information relating to a user; used to generated Identity Provider recommendations.
    - `phoneNumber` string, nullable — The phone number of the user you wish to generate a recommendation for. Will be used to look up the user's identity in the network, as well as to determine the user's geographic location.
    - `countries` string[], nullable — A list of countries, in alpha-2 ISO 3166 format, which the user is related to. This can include the user's country of residence, nationality, etc.
    - `subdivisions` string[], nullable — If one of the countries has subdivisions (for example: US states), specify those related to the user here (e.g., CA, UT, NY)
    - `ipAddresses` string[], nullable — Any IP addresses related to the user. Will be used to determine the user's geographic location.
  - `health` 'Online' | 'Offline' | 'All'

## Response `200`

OK

- RecommendProvidersResponse
  - `recommendedProviders` RecommendProviderInformation[], required
    - `id` string, required — The ID of the provider
    - `name` string, required — The friendly, human-readable name of the provider
    - `logoUrl` string, required — A URL pointing to the provider's logo
    - `subtext` string, required — The Provider's subtext recommended to be shown next to the name. This is flavor text, not a full, human-readable description of the provider.
    - `health` string, required — The current health status of the provider
    - `subProviders` SubProviderMetadata[], nullable — Metadata about the sub-providers which are available for this Provider. For example, Italy's SPID is a Provider which aggregates access to multiple sub-providers.
      - `id` string, required — The ID of the sub-provider. This cannot be used as a standalone Provider ID when creating a Session. It must be passed in via the Provider-specific input.
      - `name` string, required — The name of the sub-provider
      - `subtext` string, required — The Provider's subtext recommended to be shown next to the name. This is flavor text, not a full, human-readable description of the provider.
      - `logoUrl` string, required — A URL pointing to the logo on Trinsic's CDN. May be a PNG, JPG, or SVG image.
    - `regions` string[], required — The regions a provider is available in.
    - `countries` string[], required — A list of countries, in alpha-2 ISO 3166-1 format, that the provider is available in.
    - `subdivisions` string[], required — A list of subdivisions, in ISO 3166-2 format, that the provider is available in.
  - `remainder` RecommendProviderInformation[], required — All Providers available to your Verification Profile which are not in `recommendedProviders`
    - `id` string, required — The ID of the provider
    - `name` string, required — The friendly, human-readable name of the provider
    - `logoUrl` string, required — A URL pointing to the provider's logo
    - `subtext` string, required — The Provider's subtext recommended to be shown next to the name. This is flavor text, not a full, human-readable description of the provider.
    - `health` string, required — The current health status of the provider
    - `subProviders` SubProviderMetadata[], nullable — Metadata about the sub-providers which are available for this Provider. For example, Italy's SPID is a Provider which aggregates access to multiple sub-providers.
      - `id` string, required — The ID of the sub-provider. This cannot be used as a standalone Provider ID when creating a Session. It must be passed in via the Provider-specific input.
      - `name` string, required — The name of the sub-provider
      - `subtext` string, required — The Provider's subtext recommended to be shown next to the name. This is flavor text, not a full, human-readable description of the provider.
      - `logoUrl` string, required — A URL pointing to the logo on Trinsic's CDN. May be a PNG, JPG, or SVG image.
    - `regions` string[], required — The regions a provider is available in.
    - `countries` string[], required — A list of countries, in alpha-2 ISO 3166-1 format, that the provider is available in.
    - `subdivisions` string[], required — A list of subdivisions, in ISO 3166-2 format, that the provider is available in.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal server error

---

[API](https://skmtc.net/trinsic/apis/trinsic-api.md) · [All operations](https://skmtc.net/trinsic/apis/trinsic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trinsic/trinsic-api/versions/e57fbc634d48/schema)