---
title: "Deep links"
description: "A deep link opens the Flume app with your user already signed in, on a search, a product or a quote. It works once, within 7 days."
url: https://docs.tryflume.ai/concepts/deep-links
updated: 2026-11-11
---

# Deep links

> A deep link opens the Flume app with your user already signed in, on a search, a product or a quote. It works once, within 7 days.

A **deep link** is a one-time URL that opens the Flume app with the user signed in. It lands on one of their searches, a product from that search, or an instant quote.

## When should you create one?

Create the link from your backend at the moment the user clicks. Then open it at once.

- It works once.
- It expires 7 days after you create it.
- Flume never stores the URL. Do not store it either.

## What can a link open?

| You send | The link opens |
|---|---|
| `search_session_uuid` | That search's results |
| `search_session_uuid` and `sku_uuid` | That product. It must be a result of that search |
| `search_session_uuid`, `sku_uuid` and `quote_uuid` | That instant quote. It must be `READY` |

`search_session_uuid` is always required.

## What do the optional fields do?

| Field | Use |
|---|---|
| `target` | What the link opens: `product`, `search` or `quote`. See [What does the link open?](#what-does-the-link-open) |
| `utm_content` | Names the button that asked, for your own reporting. Max 64 characters |
| `redirect_uri` | Where Flume sends the user back to. Must be `https`, on a redirect host agreed with Flume |

## What does the link open?

Without `target`, the link opens the most specific id you send.

| You send | The link opens |
|---|---|
| `quote_uuid` | The instant quote |
| `sku_uuid`, no `quote_uuid` | The product |
| Neither | The search |

With `target`, the link opens what you name, whatever else you send.

| `target` | Needs | The link opens |
|---|---|---|
| `quote` | `quote_uuid` | The instant quote |
| `product` | `sku_uuid` | The product, also when you send a `quote_uuid` |
| `search` | Nothing more | The search |

- A `target` without the id it needs returns `422` `VALIDATION_FAILED`. `field` names the missing id.
- Flume checks every id you send, whatever `target` says. A `sku_uuid` must be a result of the search, and a `quote_uuid` must be the user's own `READY` quote for that product. A quote that is not `READY` returns `422` `QUOTE_NOT_READY`; a quote for another product returns `422` `VALIDATION_FAILED` with `field: quote_uuid`.

## How does idempotency apply?

`Idempotency-Key` is optional on `POST /deep-links`.

- A replay of the same key returns `url: null`. A link is a sign-in grant, so Flume does not repeat it.
- To get a new link, call again with a new key.

## What about the iframe's own button?

Inside the iframe, the user can open the Flume app directly. The iframe creates the link itself. You do nothing.

Your iframe tag needs `allow-popups` and `allow-popups-to-escape-sandbox` for this. See [Set up your page](https://docs.tryflume.ai/embed/host-page.md).

## What is the durable link?

`product_url` in the [save payload](https://docs.tryflume.ai/concepts/save-payload.md) is a plain link to the product.

| | Deep link | `product_url` |
|---|---|---|
| Signs the user in | Yes | No |
| Uses | One | Unlimited |
| Expires | After 7 days | Never |
| Store it | No | Yes |

## What does the user see when a link is spent?

The Flume app shows "This link has expired or was already used". Create a new link on the next click.

## Limits

- 2,000 deep links per partner per UTC day. Over it: `429` [`RATE_LIMITED`](https://docs.tryflume.ai/api/errors.md#rate_limited).
- The host of `url` depends on the environment. Do not parse or rebuild the URL.