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

# Single-Use Links

> Make sure that each respondent only replies once with single use links.

A single-use link is a survey link that accepts exactly one completed response. Instead of sharing
one URL with everyone, you hand each respondent their own URL. Once that URL has been used to
finish the survey, it stops working — everyone else's links are unaffected.

Use them when you invite a known list of people (customers, panelists, employees) and want one
response per invitation, without asking anyone to log in.

> [!NOTE]
>
> **Looking for responses tied to a specific person? Use
> [Personal Links](https://formbricks.com/docs/surveys/link-surveys/personal-links.md) instead.**
>
> Single-use links are anonymous. Formbricks limits each link to one response but does not know who
> is behind it, so it is on you to track which link you sent to whom (a custom single-use ID makes
> that easier).
>
> Personal links are generated for contacts in a segment. Each response is automatically attributed
> to that contact, links can be given an expiry date, and the CSV export maps every link to a name
> and email. Formbricks also blocks a second response from the same contact on its own, so you get
> the one-response-per-person guarantee whether or not single-use links are switched on.

## How a single-use link works

Every single-use link is your normal survey link plus a **single-use ID** (`suId`) and a
**signature** (`suToken`) that binds it to one specific survey:

```
https://app.formbricks.com/s/<surveyId>?suId=<single-use-id>&suToken=<signature>
```

When someone opens the link, Formbricks:

**1. Validates the suId**

The `suId` must be one Formbricks issued for this survey. If it is missing, malformed, or
tampered with, the respondent sees a *"This survey can only be taken by invitation"* page and
cannot answer.

**2. Looks for an existing response**

Formbricks checks whether a response with this `suId` already exists for the survey.

**3. Serves, resumes, or blocks**

No response yet → the survey opens. An unfinished response → it resumes where the respondent
left off. A finished response → they see *"The survey has already been answered."*

> [!NOTE]
>
> A link is only spent once the response is **finished**. If a respondent drops off halfway, they
> can reopen the same link and continue — they do not lose their answers and do not need a new
> link.

The `suId` is stored on the response, and the database enforces one response per `suId` per survey.
So even if two people open the same link at the same time, only the first submission is accepted.

## Encrypted vs. custom single-use IDs

Single-use links come in two modes, controlled by the **URL encryption of single-use ID** toggle.
Both are bound to their survey by the same signature. The difference is who chooses the ID and
whether it is readable.

| | **URL encryption on** (default) | **URL encryption off** |
| - | - | - |
| What `suId` looks like | An AES-encrypted, URL-encoded blob | Whatever you choose, e.g. `?suId=CUSTOMER-4711` |
| `suToken` in the URL | Required. An HMAC signature over the survey ID and `suId` | Required. An HMAC signature over the survey ID and `suId` |
| Who creates the ID | Formbricks (UI or API) | You |
| Best for | Bulk invites where the ID carries no meaning | Mapping responses back to a record in your own system |

> [!WARNING]
>
> Both modes are signed with your instance's `ENCRYPTION_KEY`, so respondents cannot forge a valid
> link by guessing an ID, and a link issued for one survey is not accepted by any other survey.
> They *can* forward their own link to someone else, so treat a single-use link as a credential.

## Create single-use links in the app

**1. Open the Distribute modal**

On the survey summary page, click **Distribute** in the top right corner and go to the
**Anonymous links** tab.

**2. Turn on Single-use links**

Toggle **Single-use links** on and confirm.

![Single use link survey settings](https://mintcdn.com/formbricks/3IQmApSwJ9OD7AdA/images/surveys/link-surveys/single-use-links/single-use-links.webp?fit=max\&auto=format\&n=3IQmApSwJ9OD7AdA\&q=85\&s=c441fe70bd2f0070fcefb60cb4738831)

> [!WARNING]
>
> Single-use and multi-use links are mutually exclusive. Enabling single-use links disables the
> multi-use link, which also disables anything built on it: website and email embeds, social
> media shares, and QR codes.

**3. Generate a batch of links**

URL encryption is on by default. Enter how many links you need (1–5,000) and click
**Generate & download links**. You get a CSV with one link per row.

**4. Or set your own single-use ID**

Turn **URL encryption of single-use ID** off, type your own ID (e.g. an invoice or customer
number), and click **Copy** to get the signed link for it.

> [!WARNING]
>
> Formbricks does not store the generated links. Save the CSV — links cannot be re-downloaded, and
> regenerating creates a different set of IDs.

## Generate links via the API

To generate links programmatically — or more than the UI batch limit in one workflow — use the
Management API:

```bash theme={null}
curl -X GET \
  'https://app.formbricks.com/api/v1/management/surveys/<surveyId>/singleUseIds?limit=100' \
  -H 'x-api-key: <your-api-key>'
```

```json theme={null}
{
  "data": [
    "https://app.formbricks.com/s/clzqym2l3...?suId=ohkj3qx6d0wdo9r3nfpm3bgj&suToken=9f2b...",
    "https://app.formbricks.com/s/clzqym2l3...?suId=ci6la2lzj63pvsp6x3eqbhff&suToken=41ce..."
  ]
}
```

The sample above is from a survey with URL encryption off, so each link carries a readable `suId`.
With encryption on the `suId` is an encrypted blob instead. Either way each link carries its own
`suToken`.

* `limit` defaults to `10` and accepts up to `5000` per call.
* The survey must be a link survey with single-use links enabled, otherwise the endpoint returns a
  400\.
* The API key needs **write** access to the survey's workspace. Even though this is a `GET`, it
  mints links that can be used to submit responses, so read-only keys are rejected.
* Links follow the survey's encryption setting. Each returned URL carries its own `suToken` in both
  modes.

See the [API reference](https://formbricks.com/docs/api-reference/management-api--survey/get-singleuse-links.md) for the full
endpoint definition.

## Find the single-use ID of a response

Each response records the `suId` it came from. In the responses table it appears as its own column,
and in the single response card you'll see it in the metadata when hovering over the avatar:

![Single use link survey metadata](https://mintcdn.com/formbricks/fuXjoDPfwirx9kHD/images/surveys/link-surveys/single-use-links/suid-metadata.webp?fit=max\&auto=format\&n=fuXjoDPfwirx9kHD\&q=85\&s=54fbcee822aa36bb567904ba87d0ea9e)

Responses fetched via the API expose the same value as the `singleUseId` field, which is how you
match a response back to the person you sent that link to.

## Submitting responses programmatically

If you build your own survey frontend and post responses to the client API, a single-use survey
requires two things in the request:

* `singleUseId` in the request body
* `meta.url` set to the full link the respondent opened, including its `suId` and `suToken`

Formbricks re-validates the URL and rejects the response if the two do not match.

> [!NOTE]
>
> With URL encryption on, the `suId` in the URL is encrypted while the API expects the decrypted
> ID, which your backend cannot derive. For programmatic submission, turn URL encryption off and
> use custom single-use IDs.

## Good to know

* **Self-hosting**: single-use links require `ENCRYPTION_KEY` to be set. Rotating that key
  invalidates every single-use link that was already handed out.
* **Since Formbricks 5.0**, unencrypted single-use links must carry a valid `suToken`. Links
  generated before 5.0 without a token are rejected — regenerate them.
* **Since Formbricks 6.0**, the same applies to *encrypted* single-use links: they now carry a
  `suToken` binding them to one survey. Encrypted links generated before 6.0 have no token and are
  rejected — regenerate them. See the
  [migration guide](https://formbricks.com/docs/self-hosting/advanced/migration.md) if you handed out a batch before upgrading.
* The *"already answered"* screen can be customized via the `singleUse.heading` and
  `singleUse.subheading` fields on the survey in the Management API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.