> ## Documentation Index > Fetch the complete documentation index at: https://www.pickfu.com/llms.txt > Use this file to discover all available pages before exploring further. # How to build PickFu surveys with URL parameters > Create PickFu surveys programmatically by encoding survey details into a URL. Learn parameter structure, encoding rules, and workflow automation tips. # 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](https://www.urlencoder.org/) 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: * `head_to_head` — Compare two options directly * `ranked` — Rank 3-8 options in order (learn more about testing multiple options) * `star_rating` — Get 1-5 star ratings * `emoji_rating` — Collect emoji-based reactions (😭 to 😀) ([learn about emoji polls](/help/what-is-an-emoji-reaction-poll-and-when-should-i-use-it)) * `single_select` — Pick one from multiple choices ([learn about single select](/help/what-is-a-multi-select-poll-and-when-should-i-use-it)) * `multi_select` — Pick multiple from a list ([learn about multi select](/help/what-is-a-multi-select-poll-and-when-should-i-use-it)) * `open_ended` — Collect written feedback ([learn about open-ended polls](/help/what-is-an-open-ended-poll-and-when-should-i-use-it)) * `click_test` — See where users click on images ([learn about click tests](/help/what-is-a-click-test-and-when-should-i-use-it)) * `five_second_test` — Show content briefly, then ask questions ([learn about 5-second tests](/help/what-is-a-5-second-test-and-when-should-i-use-it)) ``` 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](/help/which-poll-type-should-i-use)) **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](/help/how-should-i-set-up-my-survey-options)) ## 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](/help/how-do-i-test-image-sets-with-pickfu)) 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](/help/when-should-i-add-context-to-my-question)) ## 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](/help/poll-sample-size-tips)) ## 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](/help/how-do-i-target-a-specific-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](/help/what-s-the-difference-between-audience-targeting-and-demographic-questions)). **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](/help/u-s-demographic-targeting-trait-url-parameters). ``` &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](/help/what-s-the-difference-between-audience-targeting-and-demographic-questions)) ``` &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](/help/poll-sample-size-tips)) **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`](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](https://www.urlencoder.org/) 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. ``` ``` # Use case 6: Multi-question user research **Scenario**: Test product appeal, get ratings, and understand concerns. ``` ``` # 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 For full API access, create an API key at [Settings > API Keys](https://app.pickfu.com/settings/api-keys) or see the [authentication documentation](https://www.pickfu.com/docs/developers/authentication). Visit our [integrations page](/help/what-integrations-are-available-with-pickfu) for all available options. *** Related Articles * [U.S. demographic targeting trait URL parameters](/help/u-s-demographic-targeting-trait-url-parameters) * [How do I test URLs or text with PickFu?](/help/how-do-i-test-urls-or-text-with-pickfu)