> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Link

> Launch an Argyle verification session URL directly.

Hosted Link launches a verification session URL directly in a browser or secure mobile browser context.

Use Hosted Link when you want to minimize frontend development, when your security model prefers a redirect-based flow, or when your mobile application should open Link in a secure browser context instead of embedding a native SDK.

## Tradeoffs

| Hosted Link gives you                              | Hosted Link does not give you                                      |
| -------------------------------------------------- | ------------------------------------------------------------------ |
| A direct session URL to open from your application | Link callbacks                                                     |
| A browser-native or secure-browser launch model    | Frontend control over the Link instance                            |
| Lower frontend implementation effort               | Embedded SDK controls such as programmatic open and close behavior |

Track verification completion and lifecycle status changes with [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhooks. Treat redirects back to your application as a user navigation event, not as proof that the verification is complete.

## Create a session URL

Create a verification session via [`POST /v2/sessions`](/api-reference/verifications/create-a-session). The response includes a `link` URL.

Example request for a desktop browser session:

```json theme={}
{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "redirect_url": "https://your-application.com/return?state=STATE_VALUE",
    "flow_id": "12ABCD3E",
    "items": ["item_000000001", "item_000000002"],
    "language": "EN",
    "mobile_app": false
  }
}
```

<Note>
  For payroll Hosted Link sessions opened from a secure browser context in a mobile app, set `configuration.mobile_app` to `true` when creating the session.
</Note>

Example response:

```json theme={}
{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "experience": null,
    "single_use_url": false,
    "redirect_url": "https://your-application.com/return?state=STATE_VALUE",
    "flow_id": "12ABCD3E",
    "items": ["item_000000001", "item_000000002"],
    "language": "EN",
    "mobile_app": false
  },
  "link": "https://connect.argyle.com/?...",
  "data_source": "payroll"
}
```

<Note>
  Hosted Link uses verification session URLs. These session links expire after one hour, and a new session link can be created at any time by creating another session for the active verification.
</Note>

<Warning>
  The returned `link` URL is signed by Argyle to prevent tampering. Do not modify the returned URL. If you need different session settings, create a new session.
</Warning>

## Launch Hosted Link

On web, open the session `link` in the same tab, a popup window, or a separate tab.

```js theme={}
window.location.assign('SESSION_LINK')
```

On mobile, open the session `link` in a secure browser context, such as `ASWebAuthenticationSession` on iOS or Android Custom Tabs on Android.

Avoid loading Hosted Link inside an iframe. If you need iframe isolation or Link callbacks, use the [Web SDK with `connectUrl`](/link/initialization/web#initialize-with-connecturl).

## Return users to your application

Set `configuration.redirect_url` when creating the session so the user can return to your application after leaving Hosted Link. For desktop browser flows, use a regular `https://` URL. For mobile app flows, use a return target that can open your app directly:

* A custom scheme, such as `your-custom-scheme://return-to-app`
* A [Universal Link](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) on iOS or an [App Link](https://developer.android.com/studio/write/app-link-indexing) on Android

When Argyle redirects the user back, it appends two values to the redirect URL:

* `user_submission_complete`
* `user_attempted_employer_selection`

These values can help you update the user's return-page experience. They mirror the [`onClose`](/link/reference/callbacks#onclose) fields available in embedded Link, but webhooks remain the source of truth for verification completion.

A plain redirect URL is valid. For example:

```text theme={}
https://example.com/argyle-return
```

After Hosted Link redirects the user, the returned URL would include the additional parameters:

```text theme={}
https://example.com/argyle-return?user_submission_complete=true&user_attempted_employer_selection=true
```

You can also include a `state` or `nonce` value when you need to match the returning browser session to an internal user, session, or verification. A state or nonce is a unique value generated by your application, added to the redirect URL, and checked when the user returns. For example:

```text theme={}
https://example.com/argyle-return?state=abc123
```

Argyle preserves the value and appends its return parameters:

```text theme={}
https://example.com/argyle-return?state=abc123&user_submission_complete=true&user_attempted_employer_selection=true
```