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

# PickFu survey URL parameters reference

> Build PickFu survey links with pre-filled questions, options, media, targeting, and sample size using URL parameters from any app or workflow.

URL parameters let you create PickFu survey links with pre-filled questions, options, targeting, and settings. Embed these links in your application to let users launch polls without manual configuration.

## Use cases

* **SaaS platforms** — Add a "Test with PickFu" button that opens a poll pre-filled with the user's content
* **Internal tools** — Automate poll creation from dashboards or admin panels
* **Custom workflows** — Generate poll links programmatically from scripts or CI/CD pipelines

## Base URL

```
https://app.pickfu.com/ask/survey?
```

Add parameters after the `?`, separated by `&`.

## Quick example

```
https://app.pickfu.com/ask/survey?
  q1-prompt=Which+logo+is+better?
  &q1-type=head_to_head
  &q1-o1-media_url=https://example.com/logo-a.png
  &q1-o2-media_url=https://example.com/logo-b.png
  &targeting=25-34,female
  &sample_size=50
  &country=US
```

## Parameter reference

### Questions

| Parameter   | Description                 | Example                      |
| ----------- | --------------------------- | ---------------------------- |
| `q1-prompt` | Question text (URL-encoded) | `q1-prompt=Which+is+better?` |
| `q1-type`   | Poll type                   | `q1-type=head_to_head`       |

Use `q1`, `q2`, `q3` etc. for multi-question surveys.

### Options

| Parameter         | Description                       | Example                       |
| ----------------- | --------------------------------- | ----------------------------- |
| `q1-o1-value`     | Text option                       | `q1-o1-value=Option+A`        |
| `q1-o1-media_url` | Image or video URL                | `q1-o1-media_url=https://...` |
| `q1-o1-asin`      | Amazon product ASIN               | `q1-o1-asin=B08N5WRWNW`       |
| `q1-o1-image_set` | Multiple images (comma-separated) | `q1-o1-image_set=url1,url2`   |

Use `o1`, `o2`, `o3` etc. for multiple options.

### Question context

| Parameter              | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `q1-context-text`      | Explanatory text shown with the question         |
| `q1-context-media_url` | Reference image or video shown with the question |

### Targeting and settings

| Parameter     | Description                       | Example                         |
| ------------- | --------------------------------- | ------------------------------- |
| `country`     | 2-letter country code             | `country=US`                    |
| `targeting`   | Comma-separated trait permalinks  | `targeting=25-34,female,amznpr` |
| `reporting`   | Demographic breakdowns to collect | `reporting=age,gender,income`   |
| `sample_size` | Number of respondents             | `sample_size=50`                |

### Supported poll types

<Note>
  **Every response includes a written explanation by default.** Respondents are required to
  explain *why* they picked an option, ranked, rated, or clicked — that's already part of
  every poll type below except `screen_recording` (which returns a transcription instead).
  **Do not chain a second question (`q2-prompt=...`) just to ask "explain your choice" — it
  wastes a question slot (multi-question surveys are priced per question) and produces
  redundant data.** Phrase your real question in `q1-prompt`, and PickFu collects the
  explanation automatically. See [surveys overview](/docs/guides/surveys-overview) for more.
</Note>

| Type             | Parameter          | Options required |
| ---------------- | ------------------ | ---------------- |
| Head-to-head     | `head_to_head`     | 2                |
| Ranked           | `ranked`           | 3-8              |
| Open-ended       | `open_ended`       | 0-1              |
| Star rating      | `star_rating`      | 0-1              |
| Emoji rating     | `emoji_rating`     | 0-1              |
| Single select    | `single_select`    | 3-8              |
| Multi select     | `multi_select`     | 3-8              |
| Click test       | `click_test`       | 1                |
| Five-second test | `five_second_test` | 1                |

### Special parameters

| Parameter   | Description                          | Example            |
| ----------- | ------------------------------------ | ------------------ |
| `copy_from` | Duplicate an existing survey by GUID | `copy_from=ABC123` |

## Building URLs programmatically

URL-encode special characters in parameter values:

| Character | Encoded      |
| --------- | ------------ |
| Space     | `+` or `%20` |
| `&`       | `%26`        |
| `?`       | `%3F`        |
| `=`       | `%3D`        |

Example in JavaScript:

```javascript theme={null}
function buildPollUrl({ question, type, options, targeting, sampleSize }) {
  const params = new URLSearchParams();
  params.set('q1-prompt', question);
  params.set('q1-type', type);
  options.forEach((opt, i) => {
    params.set(`q1-o${i + 1}-value`, opt);
  });
  if (targeting) params.set('targeting', targeting.join(','));
  if (sampleSize) params.set('sample_size', String(sampleSize));
  return `https://app.pickfu.com/ask/survey?${params.toString()}`;
}
```

## URL parameters vs. REST API

|                       | URL parameters                          | REST API                  |
| --------------------- | --------------------------------------- | ------------------------- |
| **Best for**          | Launching polls from a UI               | Full programmatic control |
| **Auth required**     | No (user signs in on PickFu)            | Yes (API key or OAuth)    |
| **Creates draft**     | Yes (user reviews before publishing)    | Yes (publish separately)  |
| **Error handling**    | Visual (PickFu shows validation errors) | Structured JSON errors    |
| **Retrieves results** | No                                      | Yes                       |

Use URL parameters when you want users to review and publish polls themselves. Use the [REST API](/docs/api-reference/introduction) when you need full automation.

<Info>
  For a comprehensive guide with more examples and troubleshooting, see the [help center article on URL parameters](https://help.pickfu.com/en/articles/12149884).
</Info>