PickFu REST API reference and conventions

Base URL

All API requests should be made to:

https://api.pickfu.com/v1

Authentication

All endpoints require a Bearer token in the Authorization header — either an API key or an OAuth access token:

Authorization: Bearer sk_your_api_key_here

Create an API key at Settings > API Keys, or use OAuth for interactive apps. See the Authentication guide for details.

Request Format

All request bodies must be JSON
Set the Content-Type: application/json header for POST/PUT/PATCH requests
All responses are returned as JSON

Response Format

Successful responses include the requested data:

{
  "id": "abc123-def456",
  "name": "My Survey",
  "status": "completed"
}

Error Handling

Error responses include an error type and human-readable message:

{
  "error": "Not Found",
  "message": "Survey not found"
}

HTTP Status Codes

Status Code	Description
`200`	Success
`201`	Created - resource successfully created
`400`	Bad Request - invalid request body or parameters
`401`	Unauthorized - missing or invalid access token
`403`	Forbidden - insufficient permissions
`404`	Not Found - resource doesn’t exist
`409`	Conflict - the request conflicts with the resource’s current state (e.g. changing an `externalId` that is already set)
`429`	Too Many Requests - rate limit exceeded
`500`	Internal Server Error - something went wrong on our end

Validation Errors

When request validation fails, the response includes details about what went wrong:

{
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    "question is required",
    "options must have at least 2 items"
  ]
}

Rate Limits

API requests are rate-limited to 100 requests per minute per access token. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait before making more requests."
}

Implement exponential backoff in your application to handle rate limiting gracefully.

Pagination

Endpoints that return lists support pagination using page and limit query parameters:

GET /v1/surveys?page=1&limit=20

Paginated responses include metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Available Endpoints

Surveys

Create, retrieve, publish, and manage surveys.

Responses

Read responses, send follow-up questions, and rate or pin responses.

Projects

Group related surveys into projects.

Traits

Audience targeting and reporting demographics.

Media

Generate images from prompts and upload media to the CDN.

Playbooks

Step-by-step research guides.

Explore the endpoints in the sidebar to see detailed documentation for each operation.

Building surveys programmatically

Don’t add a separate “explain your reasoning” question. Every PickFu response already includes a required written explanation — respondents have to type why they picked, ranked, or rated something before they can submit. When you POST /surveys, just write your real question (e.g. “Which product image makes you more likely to click?”) and the qualitative explanation field comes back on the response automatically. Adding a second question to capture reasoning duplicates data and, in multi-question surveys, costs an extra question slot.Screen-recording surveys are the one exception — the recording itself is the answer, and the spoken response is returned as mediaTranscription rather than explanation. For every other question type the explanation field is populated on each response.

The built-in explanation lives on each response object returned by GET /surveys/{id}/responses as the explanation field. If you need to dig deeper on a specific respondent’s answer after the survey completes, use POST /surveys/{id}/responses/{responseId}/followup to send them a follow-up question through their PickFu inbox.

Correlate surveys with your own system

Pass an optional externalId string when creating a survey to tag it with a correlation key from your own system, such as an experiment ID, a ticket number, or a database key. PickFu stores the value as-is, never interprets it, and returns it on GET /surveys/{id} and GET /surveys. The field is omitted when unset.

curl -X POST https://api.pickfu.com/v1/surveys \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Logo test",
    "externalId": "exp-2026-091",
    "questions": [
      {
        "type": "head_to_head",
        "prompt": "Which logo do you prefer?",
        "options": [{ "value": "Logo A" }, { "value": "Logo B" }]
      }
    ]
  }'

Fetch surveys by key with the externalId query parameter on GET /surveys:

curl "https://api.pickfu.com/v1/surveys?externalId=exp-2026-091" \
  -H "Authorization: Bearer sk_your_api_key_here"

How externalId behaves:

Exact match only. The list filter is account-scoped, case-sensitive, and byte-exact. It is not a text search, so send the identical string every time.
Not unique. Several surveys can share one externalId, for example every poll in one experiment. The list filter returns all of them.
1-255 characters after trimming whitespace. Control characters are rejected with 400 Bad Request.
Set-once. You can claim an externalId on an existing draft via PATCH /surveys/{id}, but once set it cannot be changed, and it cannot be added after the survey is published. Either attempt returns 409 Conflict. Re-sending the same value succeeds (idempotent).
Not copied on clone. Duplicating a survey leaves externalId unset on the new draft.
Not available on mini-polls. Setting externalId together with isMiniPoll returns 400 Bad Request.

API Reference

Surveys

Responses

Tags

Traits

Playbooks

Projects

Media

PickFu REST API reference and conventions

Base URL

Authentication

Request Format

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Rate Limits

Available Endpoints

Surveys

Responses

Tags

Projects

Traits

Media

Playbooks

Building surveys programmatically

Correlate surveys with your own system

​Base URL

​Authentication

​Request Format

​Response Format

​Error Handling

​HTTP Status Codes

​Validation Errors

​Rate Limits

​Pagination

​Available Endpoints

Surveys

Responses

Tags

Projects

Traits

Media

Playbooks

​Building surveys programmatically

​Correlate surveys with your own system

Base URL

Authentication

Request Format

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Rate Limits

Pagination

Available Endpoints

Building surveys programmatically

Correlate surveys with your own system