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

# Magic links

> Shared envelope, lifecycle, and delivery model for RaaS Widgets magic links

## What is a magic link?

A magic link is a secure, time-bound URL that opens a **flow** for a specific end user identified by your `referenceId`. Creating a link is the core Partner API action.

## Envelope vs config

Links follow the v2 model:

| Part         | Owner         | Contents                                                                       |
| ------------ | ------------- | ------------------------------------------------------------------------------ |
| **Envelope** | Platform      | `referenceId`, `flow`, TTL, theme, language, metadata, presentation, lifecycle |
| **config**   | Flow strategy | Flow-specific payload (m2m `userData`, fund-request amount, …)                 |

`POST /partner/links` is discriminated by `flow`. See [Create links](/raas-widgets/guides/create-links).

## Lifecycle

Typical statuses include `created`, opened/in-progress states, and terminal states such as revoked or expired (exact set is reflected on link detail responses).

You can:

* **Create** — `POST /partner/links`
* **Get** — `GET /partner/links/{linkId}`
* **List activity** — `GET /partner/links/{linkId}/activity`
* **Revoke** — `POST /partner/links/{linkId}/revoke`

## Response shape

```json theme={null}
{
  "success": true,
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user-12345",
    "status": "created",
    "url": "https://<flow-host>/link_acme_a1b2c3d4e5f6",
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-07-23T16:00:00.000Z",
    "createdAt": "2026-07-23T15:00:00.000Z"
  }
}
```

The `url` points at the flow host configured for that slug. Deliver this URL as-is.

## Delivery channels

* Redirect or deep link in your app
* Email / SMS / push
* Native WebView — tune splash/agreement with `presentation` (see [Embed & WebView](/raas-widgets/guides/embed-webview))

## Best practices

* Reuse the same `referenceId` for the same person
* Keep TTLs short enough for your channel (default is typically 60 minutes)
* Revoke links that should no longer be usable
* Prefer webhooks over polling for open/complete signals

## Next steps

<CardGroup cols={2}>
  <Card title="Create links" icon="code" href="/raas-widgets/guides/create-links">
    Request body and examples.
  </Card>

  <Card title="Embed & WebView" icon="mobile" href="/raas-widgets/guides/embed-webview">
    Native delivery patterns.
  </Card>
</CardGroup>