---
title: "Integrate Flume"
description: "Two ways to add Flume to your product. Embed the Flume iframe, recommended and fastest, or call the Partner API and build the screens yourself."
url: https://docs.tryflume.ai/
updated: 2026-11-12
---

# Integrate Flume

> Two ways to add Flume to your product. Embed the Flume iframe, recommended and fastest, or call the Partner API and build the screens yourself.

Flume finds tile and vinyl flooring that match a photo, prices it delivered to a US ZIP code, and hands the chosen product back to your product. There are two ways to integrate.

- [Embed the iframe (recommended)](https://docs.tryflume.ai/quickstart/embed.md): The fastest way. Flume draws every screen. Your backend makes two calls and your page runs one snippet.
- [Call the API](https://docs.tryflume.ai/quickstart/api.md): You build the screens. Your backend calls verify, search, product, quote and save.

## Which one should you use?

Start with the iframe unless you need your own screens. It is the shortest path to a working integration, and Flume keeps the search and pricing screens up to date for you.

| | Embed the iframe (recommended) | Call the API |
|---|---|---|
| Time to integrate | Shortest. Two server calls and one snippet | Longer. You build and test every screen |
| Who builds the screens | Flume | You |
| Server calls you make | 2: start a session, exchange a connect code | The [six steps](https://docs.tryflume.ai/quickstart/api.md#how-it-fits-together): verify, search, product, quote, link into Flume |
| Email verification | In the iframe. You build nothing | Your own screens, with two calls |
| Search by photo and instant quote | In the iframe | `POST /search`, `POST /request-instant-quote` |
| The result in your product | A `flume:save_item` message | The `POST /save-item` response |
| New Flume features | Appear in the iframe | You add each one |
| Fits when | You want it live fast | You need Flume inside your own design |

**Diagram: Two ways to integrate, side by side.** With the iframe, Flume draws the screens and your backend makes two calls. With the API, you draw them and your backend makes every call.

```mermaid
flowchart LR
  i-screens["Flume iframe / verify, search, quote, save"]
  i-page["Your page / frames it, handles messages"]
  i-backend["Your backend / 2 server calls"]
  a-screens["Your screens / you build each one"]
  a-backend["Your backend / the six API steps"]
  a-flume["Flume servers / Partner API"]
  i-screens -.->|"4 messages"| i-page
  i-page -.->|"2 replies"| i-screens
  i-page -->|"your routes"| i-backend
  a-screens -->|"your routes"| a-backend
  a-backend -->|"every step"| a-flume
```

1. Embed the iframe, recommended: Flume draws the verify, search, quote and save screens inside an iframe.
2. Your page frames the iframe and handles its messages: four from the iframe, two replies from your page.
3. Your backend makes two server calls: start a session, and exchange a connect code.
4. Call the API: you build every screen yourself.
5. Your backend makes every call to the Partner API, in six steps: verify (two calls), search by photo, product detail, instant quote, and a link into Flume.
6. Both use the same partner key, users and save payload, and you can combine them.

- Both use the same partner key, the same users and the same sandbox.
- The save payload is the same object on both paths.
- You can combine them. The iframe itself relies on two of the same server calls, and a product saved in the iframe can be read or linked with the API.

## How it fits together

**Diagram: Who talks to whom.** Four parts and one person. Your page and the Flume iframe share the browser. Only your backend calls Flume with your key.

```mermaid
flowchart LR
  user["User"]
  page["Your page / frames the iframe"]
  backend["Your backend / holds the partner key"]
  iframe["Flume iframe / draws every screen"]
  flume["Flume servers"]
  user -->|"clicks"| page
  user -->|"searches, prices, saves"| iframe
  page -->|"your routes"| backend
  backend -->|"server calls, partner key"| flume
  page -.-> iframe
  iframe -.->|"postMessage: 4 to you, 2 back"| page
  iframe -->|"its own calls"| flume
```

1. The user clicks a button on your page.
2. Your page calls your own backend. It never calls Flume.
3. Your backend calls Flume over HTTPS, with your partner key. These are the server calls.
4. Your page frames the Flume iframe. The two talk only with postMessage: four message types from the iframe, two from your page.
5. The user searches, prices and saves inside the iframe. The iframe makes its own calls to Flume with its own short-lived credential.
6. Your partner key and user access tokens stay on your backend. They never reach the browser.

1. Flume gives you a **partner key**. It identifies your platform.
2. Each **user** verifies their email once. You get a **user access token** for them.
3. With both, your backend acts for that user: it opens the iframe, or it searches, prices and saves through the API.
4. Everything a user does also appears in their own Flume account.

Read [Authentication and keys](https://docs.tryflume.ai/concepts/authentication.md) and [Users and verification](https://docs.tryflume.ai/concepts/users.md) first. They apply to both paths. Every term is in the [glossary](https://docs.tryflume.ai/concepts/glossary.md), and every picture is on [Diagrams](https://docs.tryflume.ai/diagrams.md).

## What exists today

| Capability | Status |
|---|---|
| Sandbox | Open to partners with a sandbox key. Base URL `https://sandbox-api.tryflume.ai/partner/v1` |
| Live | Early access. Not yet open to new partners; Flume enables it by request, one partner at a time. Build in the sandbox. See [Environments](https://docs.tryflume.ai/concepts/environments.md) |
| Regions | On live, requests from some countries are refused before they reach the API |
| Categories you can search | Tile and vinyl flooring |
| Delivery | US ZIP codes. Prices are in USD |
| Keys | Issued by Flume. You rotate and revoke them yourself |
| OpenAPI document | [`/openapi.json`](https://docs.tryflume.ai/openapi.json), the file the [API reference](https://docs.tryflume.ai/api.md) is built from |
| Webhooks | Not available. Poll, or use the iframe's messages |
| SDKs and client libraries | Not available. Call the HTTP API directly |
| Self-serve keys or a dashboard | Not available. Flume issues the first key |
| A status page | Not available. Write to Flume |
| Sandbox test data | Not available. The sandbox sends real verification emails |
| Rate limit headers | Not available. A `429` from the API carries `Retry-After` |
| Reading or changing your allowed origins and hosts | Not available. Ask Flume |
| Calls from a browser | Not supported. Server to server only |

## Start here

- [Get a sandbox key](https://docs.tryflume.ai/get-a-key.md): What to send Flume, and what you get back.
- [Iframe quickstart](https://docs.tryflume.ai/quickstart/embed.md): Recommended. Open the iframe and receive a saved item.
- [API quickstart](https://docs.tryflume.ai/quickstart/api.md): Verify a user, search by photo, get a quote.
- [API reference](https://docs.tryflume.ai/api.md): Every endpoint, field and error.

## For language models and agents

- Every page has a Markdown version. Add `.md` to its URL.
- [`/llms.txt`](https://docs.tryflume.ai/llms.txt) lists every page, with a reading order and the rules in brief. [`/llms-full.txt`](https://docs.tryflume.ai/llms-full.txt) holds the whole site in one file.
- [`/openapi.json`](https://docs.tryflume.ai/openapi.json) is the OpenAPI 3.1 document for the Partner API.
- Every page has a menu: copy it as Markdown, or open it in ChatGPT or Claude.