Create a deep link

POSThttps://sandbox-api.tryflume.ai/partner/v1/deep-linksCopy

RequestReturnsErrors

Creates a one-time link that opens the Flume app with the user signed in.

• Create it when the user clicks, and open it at once. It works once, within 7 days.
• search_session_uuid is required. Add sku_uuid to open a product from that search.
• A replay of the same Idempotency-Key returns url: null.

Guide: Open Flume signed in

curl

curl -X POST "https://sandbox-api.tryflume.ai/partner/v1/deep-links" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY" \
  -H "X-Flume-User-Token: $FLUME_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f",
  "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30"
}'

Python

import os

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
    "X-Flume-User-Token": os.environ["FLUME_USER_TOKEN"],
}

response = requests.post(
    "https://sandbox-api.tryflume.ai/partner/v1/deep-links",
    headers=headers,
    json={
        "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f",
        "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/deep-links", {
  method: "POST",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
    "X-Flume-User-Token": process.env.FLUME_USER_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f",
    "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Response: 201

{
  "url": "https://app.tryflume.ai/?utm_source=acme&utm_medium=partner#/l/dlk_q3Vh8yT…",
  "expires_at": "2026-10-23T09:14:22Z"
}

Request

Headers

Header	Required	Description
X-Flume-Partner-Key	Yes	Your partner key. See Authentication and keys.
X-Flume-User-Token	Yes	The access token of the user you call for. See Users and verification.
Idempotency-Key	No	One value per user action, 1 to 255 characters. A retry with the same value returns the first response.

Body

Send application/json. A field the API does not list returns a 422 that names it.

• search_session_uuidstring (UUID)Required

  One of the user's searches. Without sku_uuid, the link opens its results.

• sku_uuidstring (UUID) or nullOptional

  A product to open. It must be a result of that search.

• quote_uuidstring (UUID) or nullOptional

  An instant quote to open, with sku_uuid. It must be READY and belong to the user.

• targetenum or nullOptional

  What the link opens: product, search or quote. Optional. Without it, the link opens the most specific id you send: quote_uuid, then sku_uuid, then the search. When set, it wins: product with a quote_uuid opens the product. quote needs quote_uuid, and product needs sku_uuid. Every id you send is checked, whatever target says.

• utm_contentstring or nullOptional

  A name for the button that asked, for your own reporting.

  • Max 64 characters
• redirect_uristring or nullOptional

  Where Flume sends the user back to. It must be an https URL on a redirect host agreed with Flume.

  • Max 2,048 characters

Returns

201 with these fields. Every field is always present. A field with no value is null.

• urlstring or null

  The link. It works once, within 7 days. null when you replay an Idempotency-Key.

• expires_atstring

  When the link stops working, in UTC.

Errors

Every error uses one envelope. Branch on error.code.

Status	Code	Meaning
401	EMBED_TOKEN_INVALID	You sent an Authorization header and no X-Flume-Partner-Key. Flume read the call as one from its own iframe.
401	PARTNER_KEY_INVALID	The partner key is missing, unknown, revoked, expired, or from the other environment. On live, also a platform Flume has not enabled yet.
401	USER_TOKEN_INVALID	The user access token is unknown, revoked, another partner's, or replaced by a later verification. A verification in the iframe replaces it too.
403	USER_ACCOUNT_CLOSED	The user's email belongs to a Flume account that Flume has closed.
403	USER_NOT_CONNECTED	No X-Flume-User-Token header was sent.
404	NOT_FOUND	The thing does not exist, or is not this user's. A search id that is not a UUID also returns this code.
404	SESSION_NOT_FOUND	The search does not exist, or is another user's.
409	IDEMPOTENCY_IN_PROGRESS	The first call with this key is still running.
422	IDEMPOTENCY_KEY_REUSED	The key was already used with a different body.
422	QUOTE_NOT_READY	The quote is not READY. On POST /save-item it also covers a quote that expired, is not this user's, lacks the option you named, or is under that option's minimum order.
422	SKU_NOT_IN_SEARCH	The product was not a result of the search you named.
422	VALIDATION_FAILED	A field is missing, unknown or has an unusable value. field names it as a dotted path. Some refusals carry the detail in details and leave field empty.
429	RATE_LIMITED	Today's limit for this call is used up. Retry-After is the number of seconds until 00:00 UTC.
500	INTERNAL	Something failed on Flume's side.