PickFu survey URL parameters reference

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

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 for more.

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:

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 when you need full automation.

For a comprehensive guide with more examples and troubleshooting, see the help center article on URL parameters.

Surveys

Organization

Reference

PickFu survey URL parameters reference

Use cases

Base URL

Quick example

Parameter reference

Questions

Options

Question context

Targeting and settings

Supported poll types

Special parameters

Building URLs programmatically

URL parameters vs. REST API

​Use cases

​Base URL

​Quick example

​Parameter reference

​Questions

​Options

​Question context

​Targeting and settings

​Supported poll types

​Special parameters

​Building URLs programmatically

​URL parameters vs. REST API

Use cases

Base URL

Quick example

Parameter reference

Questions

Options

Question context

Targeting and settings

Supported poll types

Special parameters

Building URLs programmatically

URL parameters vs. REST API