canonical: https://jentic.com/apis/pickfu.com/pickfu

# PickFu API

The PickFu API creates consumer polls, targets them at a respondent panel by demographic traits, and returns the answers. A survey holds questions of types such as head_to_head, ranked, open_ended, click_test, and van_westendorp, is created as a draft, and is published to start collecting responses, then stopped or extended with more respondents. Results come back as individual responses with written explanations and demographic traits, AI-generated summaries, click-test heatmaps and click regions, Van Westendorp price curves, and CSV, PDF, and PNG exports, alongside templates, playbooks, projects, tags, and AI image generation for poll options.

## For AI agents

Create, target, and publish PickFu consumer polls such as head-to-head and ranked questions, then read responses, AI summaries, click-test heatmaps, price sensitivity results, and CSV exports.

## Scope

Does not send surveys to your own customer list, host embedded web forms, or run email campaigns. Use for consumer panel polls and their results only.

## Capabilities

- Draft a survey with head_to_head, ranked, open_ended, click_test, or van_westendorp questions and a sampleSize
- Target respondents by demographic traits per country and choose reporting breakdowns
- Publish a draft survey to the panel, stop a live one, or extend a completed one with more respondents
- Read individual responses filtered by question_id, explanation text, or respondent traits
- Get click-test heatmaps and click-region counts, and Van Westendorp price sensitivity curves
- Search completed surveys semantically and export results as CSV, PDF, or PNG
- Generate an AI image from a prompt or upload media to use as poll options

## Use cases

### Design-testing agent through Jentic

An AI agent helping a seller choose between product images can run a real consumer poll instead of guessing. Through Jentic the agent searches for 'create a consumer poll', loads the PickFu createSurvey operation with its input schema, drafts a head_to_head question with both images and targeting traits, publishes it, and later reads the responses and AI summary. The bearer token is injected at call time by your own Jentic One instance, and publishing deducts credits from your PickFu account.

Example prompt: Call POST /surveys with a head_to_head question for two uploaded images, country US, and sampleSize 50, then call POST `/surveys/{id}/publish` and later GET `/surveys/{id}` for the results and summary

### Audience-segmented feedback analysis

Product teams want to know not just which option won but who preferred it and why. Survey responses include the respondent's answer, written explanation, and demographic traits, and can be filtered by trait permalinks such as male or age-25-34, by question_id, or by keyword in the explanation. Pinning and rating responses keeps the most useful comments easy to find.

Example prompt: Call GET `/surveys/{id}/responses` with traits 'female,age-25-34' and text 'price', then call PUT `/surveys/{id}/responses/{responseId}/pin` with pinned true on the clearest comment

### Click tests and price sensitivity

Click-test questions show where respondents click on an image, such as a landing page or app store listing. PickFu returns a rendered heatmap PNG and named click regions with first-click or all-click counts. For pricing research, van_westendorp questions return the four cumulative price curves and the named price intersections PMC, OPP, IPP, and PME.

Example prompt: Call GET `/surveys/{id}/questions/{questionId}/van-westendorp` for a completed pricing question and report the optimal price point and acceptable price range

### Research repository search and export

Teams that have run many polls can query their own history. Semantic search over completed surveys takes a natural-language query and returns matching results for the team, and the exports operation returns download URLs for CSV results, PDF reports, and PNG screenshots, with the CSV stream available in v1 or v2 format.

Example prompt: Call POST `/semantic-search/search` with query 'packaging colour preferences', then GET `/surveys/{id}/exports` for the best match and return its CSV and PDF links

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/surveys` | Create a draft survey |
| POST | `/surveys/{id}/publish` | Publish a draft survey |
| GET | `/surveys/{id}` | Get a survey with results and summaries |
| GET | `/surveys/{id}/responses` | List individual responses |
| GET | `/traits/targeting` | List audience targeting traits |
| GET | `/surveys/{id}/questions/{questionId}/heatmap` | Get a click-test heatmap |
| POST | `/semantic-search/search` | Search completed surveys semantically |
| GET | `/surveys/{id}/exports` | Get survey export links |

## Key resources

- **Surveys and questions** — Draft, published, stopped, and archived polls with question types, options, targeting, and sampleSize
- **Responses and analysis** — Individual answers with explanations and traits, follow-up answers, heatmaps, click regions, and Van Westendorp results
- **Traits, templates, and playbooks** — Targeting and reporting traits by country, ready-made poll templates, mockup templates, and research playbooks
- **Projects, tags, media, and API keys** — Organising surveys, uploading or generating option media, and managing the account's API keys

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 56 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 94 / 100
  - Security: 75 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/pickfu.com/pickfu/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring PickFu by hand means creating an API key or running its OAuth 2.0 flow, sending the bearer token, choosing between the production and sandbox hosts, and polling surveys until responses arrive. Through Jentic you install once, import PickFu from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** PickFu puts the survey id in the URL path (`/surveys/{id}/publish`, `/surveys/{id}/responses`), so a rule can pin your agent to one survey and the operations you pick. You choose the operations it may call, so credit-spending or destructive ones like publishing, adding respondents, or deleting a survey are not included unless you add them.
- **Credential handling:** Your PickFu token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a consumer poll' or 'get survey responses by demographic', and Jentic returns the matching PickFu operation with its input schema, including question types and targeting traits, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SurveyMonkey API** — Build and send surveys to your own contacts and collect responses
- **Qualtrics API** — Survey and experience management for larger research programmes
- **Typeform API** — Conversational forms for collecting answers from your own users

## FAQ

### What authentication does the PickFu API use?

The PickFu API authenticates with an HTTP bearer token (bearerAuth) per its OpenAPI spec: either a PickFu API key or an OAuth 2.0 access token, sent as 'Authorization: Bearer'. The CSV export stream also accepts a short-lived signed token in its t query parameter, issued by the survey exports operation. Through Jentic the token is stored by your own instance and attached at call time.

### Does publishing a survey with the PickFu API cost money?

Yes. Per the spec, POST `/surveys/{id}/publish` requires sufficient credits on the account, and credits are deducted when the survey is published. Only draft surveys can be published, and a survey needs at least one question with options. Stopping a live survey with POST `/surveys/{id}/stop` is irreversible.

### What are the rate limits for the PickFu API?

Per the OpenAPI spec, only selected endpoints enforce per-caller rate limits, currently the CSV export endpoints, which return 429 Too Many Requests when exceeded. The CSV export at GET `/surveys/{id}/exports/csv` is limited to 10 requests per minute per caller. See the PickFu developer docs at https://www.pickfu.com/docs/developers/authentication and each endpoint description for current budgets.

### Is there a PickFu MCP server?

You don't need an MCP server to give your agent PickFu. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the survey and response operations on demand without loading another server's tool definitions into its context.

### How do I run a poll through Jentic?

Search Jentic for 'create a consumer poll', load the POST /surveys operation, and execute it with a name, a question such as head_to_head with two options, targeting traits, and a sampleSize. Then call the publish operation and read results with GET `/surveys/{id}.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the PickFu API?

Yes. Write a rule that allows POST /surveys and PATCH `/surveys/{id}` but not the publish operation, and the agent can draft polls for your review without spending credits, while you publish them yourself. Every call it makes is logged for review.