Skip to main content

How to build PickFu surveys with URL parameters

Create PickFu surveys programmatically by encoding your survey details directly into a URL. This guide shows you how to build custom survey links for seamless integration with your workflow.

Updated today

When to use URL parameters

URL parameters let you pre-populate survey fields automatically, making them ideal when you want to:

  • Automate survey creation from your applications or tools

  • Integrate PickFu into existing workflows without manual data entry

  • Build custom interfaces that feed directly into PickFu's survey builder

  • Share pre-configured surveys with team members or clients

  • Test multiple variations quickly by changing URL values

What you'll need: Basic understanding of URL structure and how query parameters work.

Understanding the basics

The survey endpoint

All PickFu surveys start with this base URL:

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

You'll add your survey details after the ? symbol using parameters separated by &:

https://app.pickfu.com/ask/survey?q1-prompt=Your+question&q1-type=head_to_head&q1-o1-value=Option+A&q1-o2-value=Option+B

Parameter structure

Parameters follow a consistent pattern:

q1-prompt=Which+logo+is+better?

Here's what each part means:

  • q1 = Question number (q1 for first question, q2 for second, etc.)

  • prompt = The parameter name (what you're setting)

  • Which+logo+is+better? = The value (with spaces replaced by +)

Important rules

  1. URL encoding required: Special characters must be encoded:

    • Spaces become + or %20

    • Question marks become %3F

    • Ampersands become %26

    • Use an online URL encoder when needed

  2. Question numbers start at 1: Use q1 for your first question, q2 for the second, and so on

  3. Option numbers start at 1: Use q1-o1 for the first option, q1-o2 for the second, etc.

Quick start: Copy and paste examples

Here are ready-to-use templates you can customize:

Compare two text options:

https://app.pickfu.com/ask/survey?q1-prompt=Which+name+is+better?&q1-type=head_to_head&q1-o1-value=Name+A&q1-o2-value=Name+B

Get a star rating:

https://app.pickfu.com/ask/survey?q1-prompt=Rate+this+design&q1-type=star_rating&q1-o1-value=Design+Concept

Rank multiple options:

https://app.pickfu.com/ask/survey?q1-prompt=Rank+your+favorites&q1-type=ranked&q1-o1-value=Option+1&q1-o2-value=Option+2&q1-o3-value=Option+3&q1-o4-value=Option+4

Collect open-ended feedback:

https://app.pickfu.com/ask/survey?q1-prompt=What+do+you+think+about+this+idea?&q1-type=open_ended

Compare two images:

https://app.pickfu.com/ask/survey?q1-prompt=Which+design+is+better?&q1-type=head_to_head&q1-o1-media_url=https://example.com/image1.jpg&q1-o2-media_url=https://example.com/image2.jpg

Building your survey URL step by step

Step 1: Start with the base URL

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

Step 2: Add your question

Use q1-prompt= followed by your question text (with spaces as +):

https://app.pickfu.com/ask/survey?q1-prompt=Which+logo+looks+more+professional?

Step 3: Choose your question type

Add &q1-type= followed by one of these types:

https://app.pickfu.com/ask/survey?q1-prompt=Which+logo+looks+more+professional?&q1-type=head_to_head

Step 4: Add your options

Add each option using &q1-o1-value=, &q1-o2-value=, etc.:

https://app.pickfu.com/ask/survey?q1-prompt=Which+logo+looks+more+professional?&q1-type=head_to_head&q1-o1-value=Logo+with+blue+background&q1-o2-value=Logo+with+white+background

Question types explained

Head-to-Head comparison

Best for: Comparing exactly two options to see which performs better

Options needed: Exactly 2

Text example:

?q1-prompt=Which+slogan+is+better?&q1-type=head_to_head&q1-o1-value=Slogan+A&q1-o2-value=Slogan+B

Image example:

?q1-prompt=Which+design+is+better?&q1-type=head_to_head&q1-o1-media_url=https://example.com/design-a.jpg&q1-o2-media_url=https://example.com/design-b.jpg

Ranked choice

Best for: Understanding preference order across 3-8 options (see poll type tips)

Options needed: 3-8

Example:

?q1-prompt=Rank+these+names+from+best+to+worst&q1-type=ranked&q1-o1-value=TechFlow&q1-o2-value=CloudSphere&q1-o3-value=DataWise&q1-o4-value=NetPulse

Star rating

Best for: Getting quick 1-5 star ratings on a single item

Options needed: 0 or 1 (optional)

Simple rating:

?q1-prompt=Rate+this+product+concept&q1-type=star_rating

Rating with image:

?q1-prompt=Rate+this+design&q1-type=star_rating&q1-o1-media_url=https://example.com/product.jpg

Emoji rating

Best for: Capturing emotional reactions on a scale from 😭 to 😀

Options needed: 0 or 1

Example:

?q1-prompt=How+do+you+feel+about+this+ad?&q1-type=emoji_rating&q1-o1-media_url=https://example.com/ad.jpg

Single select

Best for: Choosing one option from 3-8 choices

Options needed: 3-8

Example:

?q1-prompt=Which+feature+is+most+important?&q1-type=single_select&q1-o1-value=Fast+shipping&q1-o2-value=Low+price&q1-o3-value=High+quality&q1-o4-value=Good+reviews

Multi select

Best for: Selecting multiple options from 3-8 choices

Options needed: 3-8

Example:

?q1-prompt=Which+benefits+matter+to+you?&q1-type=multi_select&q1-o1-value=Free+shipping&q1-o2-value=Money+back+guarantee&q1-o3-value=24/7+support&q1-o4-value=Premium+packaging

Open-ended

Best for: Collecting detailed written feedback

Options needed: 0 or 1 (optional context image)

Text only:

?q1-prompt=What+concerns+do+you+have+about+this+product?&q1-type=open_ended

With image:

?q1-prompt=What+would+you+improve?&q1-type=open_ended&q1-o1-media_url=https://example.com/product.jpg

Click test

Best for: UX testing to see where users click on designs

Options needed: Exactly 1 (the image to test)

Single click:

?q1-prompt=Click+where+you+would+buy&q1-type=click_test&q1-o1-media_url=https://example.com/landing-page.jpg

Multiple clicks (e.g., 3 clicks):

?q1-prompt=Click+the+3+elements+that+catch+your+attention&q1-type=click_test-3_clicks&q1-o1-media_url=https://example.com/homepage.jpg

Five-second test

Best for: First impression testing — shows content briefly then asks questions

Options needed: Exactly 1 (the image to show)

Example:

?q1-prompt=What+do+you+remember+about+this+design?&q1-type=five_second_test&q1-o1-media_url=https://example.com/design.jpg

Adding different types of options

Learn how to add various types of content to your surveys. (See poll option tips)

Text options

Use q{N}-o{M}-value= for text-based options:

&q1-o1-value=Option+A 
&q1-o2-value=Option+B 
&q1-o3-value=Option+C

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Choose+your+favorite&q1-type=ranked&q1-o1-value=Option+A&q1-o2-value=Option+B&q1-o3-value=Option+C

Image and video options

Use q{N}-o{M}-media_url= for visual content:

Supported formats:

  • Images: .png, .jpg, .jpeg, .gif, .webp, .bmp, .svg

  • Videos: .mp4, .mov, .mpeg, .avi, .webm, .mkv

Example:

&q1-o1-media_url=https://example.com/design1.jpg 
&q1-o2-media_url=https://example.com/design2.jpg

Important notes:

  • Images must be publicly accessible (no password protection)

  • Use direct image URLs, not webpage URLs

  • HTTPS links work best

Amazon product options (ASIN)

Test Amazon products using their ASIN codes:

What's an ASIN? A 10-character Amazon product identifier like B08N5WRWNW

How to find it:

  1. Go to any Amazon product page

  2. Scroll to the "Product Information" section

  3. Look for "ASIN: B08N5WRWNW"

  4. Copy the code

Example:

&q1-o1-asin=B08N5WRWNW 
&q1-o2-asin=B079VSXNWR

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Which+product+looks+better?&q1-type=head_to_head&q1-o1-asin=B08N5WRWNW&q1-o2-asin=B079VSXNWR

Optional: Control how products display:

&q1-o1-mockup_rendering=listing  (shows as product listing) 
&q1-o1-mockup_rendering=serp     (shows as search result)

Image stacks (multiple images per option)

Show multiple images for a single option, like a product gallery. (Learn more about testing image sets)

Use q{N}-o{M}-image_set= with comma-separated URLs (max 6 images):

&q1-o1-image_set=https://example.com/img1.jpg,https://example.com/img2.jpg,https://example.com/img3.jpg

Choose layout:

&q1-o1-image_stack_layout=amz-horizontal  (side by side) 
&q1-o1-image_stack_layout=amz-vertical    (stacked)

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Rate+this+product&q1-type=star_rating&q1-o1-image_set=https://example.com/front.jpg,https://example.com/back.jpg,https://example.com/detail.jpg&q1-o1-image_stack_layout=amz-horizontal

Pro tip: You can mix ASINs and image URLs in the same image set:

&q1-o1-image_set=B08N5WRWNW,https://example.com/custom.jpg,B079VSXNWR

Adding context to your questions

Context provides additional information or instructions that appear with your question. (Learn more about question context)

Text context

Use q{N}-context-text= to add explanatory text:

&q1-context-text=Please+consider+the+target+audience+is+millennials

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Which+ad+is+better?&q1-type=head_to_head&q1-context-text=Target+audience:+millennials+aged+25-35&q1-o1-media_url=https://example.com/ad1.jpg&q1-o2-media_url=https://example.com/ad2.jpg

Image or video context

Use q{N}-context-media_url= to show reference images:

&q1-context-media_url=https://example.com/product-specs.jpg

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Rate+this+product&q1-type=star_rating&q1-context-text=New+organic+skincare+line&q1-context-media_url=https://example.com/product-info.jpg&q1-o1-asin=B0DMFF4TMZ

Creating multi-question surveys

Build comprehensive surveys by adding multiple questions using q1, q2, q3, etc. (Learn more about multi-question surveys)

Two-question example

Question 1: Ranked choice

Question 2: Open-ended feedback

https://app.pickfu.com/ask/survey? 
q1-prompt=Rank+these+names& 
q1-type=ranked& 
q1-o1-value=Name+A& 
q1-o2-value=Name+B& 
q1-o3-value=Name+C& 
q2-prompt=Why+did+you+choose+that+order?& 
q2-type=open_ended

Three-question example

Question 1: Image comparison

Question 2: Star rating

Question 3: Multiple choice

https://app.pickfu.com/ask/survey? 
q1-prompt=Which+design+is+better?& 
q1-type=head_to_head& 
q1-o1-media_url=https://example.com/design1.jpg& 
q1-o2-media_url=https://example.com/design2.jpg& 
q2-prompt=Rate+your+favorite+design& 
q2-type=star_rating& 
q2-o1-media_url=https://example.com/winner.jpg& 
q3-prompt=What+feature+matters+most?& 
q3-type=single_select& 
q3-o1-value=Color& 
q3-o2-value=Layout& 
q3-o3-value=Typography& 
q3-o4-value=Imagery

Targeting your audience

Learn how to reach the right respondents for your survey. (Learn more about choosing your audience)

Set the country

Use country= with a 2-letter country code:

Supported countries: US, CA, GB (or UK), AU, DE, FR, ES, IT, JP, MX, BR, KR, ZA, PL

&country=CA

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Which+product+name+works+for+Canadians?&q1-type=ranked&q1-o1-value=Name+A&q1-o2-value=Name+B&q1-o3-value=Name+C&country=CA

Target specific demographics

Use targeting= with comma-separated trait permalinks. (Learn about audience targeting).

Common traits:

  • Age ranges: 18-24, 25-34, 35-44, 45-54, 55-64, 65-plus

  • Gender: male, female

  • Income: under-25k, 25-50k, 50-75k, 75-100k, 100k-plus

  • Education: high-school, some-college, bachelors, masters, doctorate

  • Location: urban, suburban, rural

View our full list of available demographic targeting trait URL parameters in this guide.

&targeting=25-34,female,50-75k

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Which+ad+appeals+to+you?&q1-type=head_to_head&q1-o1-media_url=https://example.com/ad1.jpg&q1-o2-media_url=https://example.com/ad2.jpg&targeting=25-34,female,urban&country=US

Collect demographic data

Use reporting= to ask demographic questions at the end. (Learn about demographic reporting)

&reporting=age,income,education

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Rate+this+product&q1-type=star_rating&q1-o1-asin=B08N5WRWNW&reporting=age,gender,income&country=US

Advanced features

Set sample size

Use sample_size= to specify how many responses you want. (Learn about poll sample sizes)

Valid values: 5, 15, 30, 50, 75, 100, 200, 300, 500, 1000

&sample_size=100

Complete URL:

https://app.pickfu.com/ask/survey?q1-prompt=Test+question&q1-type=head_to_head&q1-o1-value=A&q1-o2-value=B&sample_size=100&country=US

Duplicate existing surveys

Use copy_from= to duplicate a survey you've already created:

How to find the survey GUID:

  1. Go to your survey

  2. Look at the URL: https://app.pickfu.com/ask/ABC123/survey

  3. Copy ABC123 (the GUID)

https://app.pickfu.com/ask/survey?copy_from=ABC123

This creates an editable copy of survey ABC123.

[IMAGE: screenshot showing survey URL with GUID highlighted in red rectangle — alt: "Location of survey GUID in PickFu survey URL"]

Troubleshooting common issues

Survey doesn't load or shows an error

Check these:

  1. URL starts with [https://app.pickfu.com/ask/survey](<https://app.pickfu.com/ask/survey>)?

  2. Special characters are URL-encoded

  3. Parameters are separated by &

Test your URL in a URL encoder tool first to catch encoding issues.

Images don't appear

Common fixes:

  1. Verify image is publicly accessible (try opening in a private browser window)

  2. Use direct image URL, not a webpage URL

  3. Confirm URL ends with image extension (.jpg, .png, etc.)

  4. Use HTTPS instead of HTTP when possible

Wrong number of options error

Check question type requirements:

  • Head-to-head: exactly 2 options

  • Ranked: 3-8 options

  • Single/Multi select: 3-8 options

  • Star/Emoji rating: 0-1 options

  • Open-ended: 0-1 options

  • Click test: exactly 1 option

Question type not working

Verify:

  1. Question type is spelled correctly

  2. Valid types: head_to_head, ranked, star_rating, emoji_rating, single_select, multi_select, open_ended, click_test, five_second_test

  3. Use underscores (not hyphens) in type names

Special characters breaking the URL

Use URL encoding:

  • Space → + or %20

  • & → %26

  • = → %3D

  • ? → %3F

  • # → %23

  • % → %25

Pro tip: Use an online URL encoder for complex text.

Amazon ASIN not working

Verify:

  1. ASIN is exactly 10 characters

  2. Product is from Amazon US marketplace

  3. Product is currently active and available

Context not showing

Check:

  1. Parameter names are correct: q1-context-text or q1-context-media_url

  2. Media URL is publicly accessible

  3. Context is added to the correct question number

Real-world use cases

Use case 1: A/B test product names

Scenario: You have two product names and need to know which resonates more.

https://app.pickfu.com/ask/survey?q1-prompt=Which+name+sounds+better+for+a+project+management+tool?&q1-type=head_to_head&q1-o1-value=TaskFlow&q1-o2-value=WorkStream&sample_size=50&country=US

Use case 2: Test multiple logo designs

Scenario: You have four logo variations and want them ranked.

https://app.pickfu.com/ask/survey?q1-prompt=Rank+these+logos+from+best+to+worst&q1-type=ranked&q1-o1-media_url=https://example.com/logo1.png&q1-o2-media_url=https://example.com/logo2.png&q1-o3-media_url=https://example.com/logo3.png&q1-o4-media_url=https://example.com/logo4.png&sample_size=75

Use case 3: Product packaging with context

Scenario: Test packaging while providing product information.

https://app.pickfu.com/ask/survey?q1-prompt=Which+packaging+would+you+buy?&q1-type=head_to_head&q1-context-text=Organic+coffee+beans+from+Colombia&q1-context-media_url=https://example.com/product-story.jpg&q1-o1-media_url=https://example.com/package1.jpg&q1-o2-media_url=https://example.com/package2.jpg&sample_size=100

Use case 4: Amazon product comparison

Scenario: Compare two Amazon products side by side.

https://app.pickfu.com/ask/survey?q1-prompt=Which+product+looks+more+appealing?&q1-type=head_to_head&q1-o1-asin=B08N5WRWNW&q1-o1-mockup_rendering=listing&q1-o2-asin=B079VSXNWR&q1-o2-mockup_rendering=listing&sample_size=50

Use case 5: Landing page click test

Scenario: Understand where users naturally click on your landing page.

<https://app.pickfu.com/ask/survey?q1-prompt=Click+where+you+would+click+to+learn+more&q1-type=click_test-3_clicks&q1-o1-media_url=https://example.com/landing-page.jpg&sample_size=30>

Use case 6: Multi-question user research

Scenario: Test product appeal, get ratings, and understand concerns.

<https://app.pickfu.com/ask/survey?q1-prompt=How+appealing+is+this+product?&q1-type=emoji_rating&q1-o1-media_url=https://example.com/product.jpg&q2-prompt=Rate+the+price+point&q2-type=star_rating&q2-o1-value=$49.99&q3-prompt=What+concerns+do+you+have?&q3-type=open_ended&sample_size=50&reporting=age,income>

Quick reference

Question types

Type

Parameter

Options Needed

Head-to-Head

head_to_head

2

Ranked

ranked

3-8

Star Rating

star_rating

0-1

Emoji Rating

emoji_rating

0-1

Single Select

single_select

3-8

Multi Select

multi_select

3-8

Open-Ended

open_ended

0-1

Click Test

click_test

1

Five-Second Test

five_second_test

1

Parameter types

Category

Parameter

Format

Example

Question

Prompt

q{N}-prompt=TEXT

q1-prompt=Your+question

Type

q{N}-type=TYPE

q1-type=ranked

Options

Text

q{N}-o{M}-value=TEXT

q1-o1-value=Option+A

Media

q{N}-o{M}-media_url=URL

q1-o1-media_url=https://...

ASIN

q{N}-o{M}-asin=CODE

q1-o1-asin=B08N5WRWNW

Image Set

q{N}-o{M}-image_set=URLS

q1-o1-image_set=url1,url2

Context

Text

q{N}-context-text=TEXT

q1-context-text=Instructions

Media

q{N}-context-media_url=URL

q1-context-media_url=https://...

Targeting

Country

country=CODE

country=US

Demographics

targeting=TRAITS

targeting=25-34,female

Reporting

reporting=TRAITS

reporting=age,income

Config

Sample Size

sample_size=N

sample_size=50

Special

Duplicate

copy_from=GUID

copy_from=ABC123

URL encoding

Character

Encoded

Character

Encoded

Space

+ or %20

&

%26

=

%3D

?

%3F

#

%23

%

%25

/

%2F

:

%3A

Country codes

Country

Code

Country

Code

United States

US

Canada

CA

United Kingdom

GB or UK

Australia

AU

Germany

DE

France

FR

Spain

ES

Italy

IT

Japan

JP

Mexico

MX

Brazil

BR

South Korea

KR

South Africa

ZA

Poland

PL

Next steps

For more robust integrations

Consider using PickFu's API instead of URL parameters when you need:

  • Better error handling and validation

  • Programmatic poll management

  • Webhook support for results

  • Structured response data

  • Poll status monitoring

For no-code automation

Try PickFu's Zapier integration to:

  • Trigger polls automatically from other apps

  • Connect with 6,000+ tools (Google Sheets, Slack, Airtable, etc.)

  • Automate results processing

  • Build multi-step workflows

  • Link accounts for free

Contact PickFu support to learn about API access or visit our Zapier integration page for setup assistance.

Related Articles
U.S. demographic targeting trait URL parameters
Did this answer your question?