Skip to main content
POST
/
surveys
Create survey
curl --request POST \
  --url https://api.pickfu.com/v1/surveys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "questions": [
    {
      "prompt": "<string>",
      "context": {
        "text": "<string>",
        "mediaUrl": "<string>"
      },
      "options": [
        {
          "value": "<string>",
          "mediaUrl": "<string>",
          "asin": "<string>",
          "imageSet": [
            "<string>"
          ],
          "mockup": {
            "image": "<string>",
            "title": "<string>",
            "numRatings": 123,
            "reviewScore": 123,
            "price": 123,
            "currency": "<string>"
          }
        }
      ]
    }
  ],
  "name": "<string>",
  "projectId": "<string>",
  "projects": [
    "<string>"
  ],
  "tags": [
    {
      "id": 123
    }
  ],
  "targeting": [
    "<string>"
  ],
  "reporting": [
    "<string>"
  ],
  "country": "<string>",
  "sampleSize": "<string>",
  "surveyIntent": "<string>",
  "isMiniPoll": true
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "country": "<string>",
    "sampleSize": 123,
    "numResponses": 123,
    "status": "<string>",
    "targeting": [
      "<string>"
    ],
    "reporting": [
      "<string>"
    ],
    "tags": [
      {
        "id": 123,
        "name": "<string>"
      }
    ],
    "projects": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "surveyUrl": "<string>",
    "surveyIntent": "<string>",
    "questions": [
      {
        "id": "<string>",
        "type": "<string>",
        "variant": "<string>",
        "value": "<string>",
        "translation": "<string>",
        "options": [
          {
            "id": "<string>",
            "label": "<string>",
            "value": "<string>",
            "type": "<string>",
            "translation": "<string>",
            "product": {
              "asin": "<string>",
              "title": "<string>",
              "price": 123,
              "rating": 123,
              "reviews": 123,
              "image": "<string>"
            },
            "imageSetDirection": "<string>",
            "mockupType": "<string>"
          }
        ],
        "context": {
          "type": "<string>",
          "value": "<string>",
          "translation": "<string>"
        },
        "responses": [
          {
            "id": "<string>",
            "pinned": true,
            "explanation": "<string>",
            "translation": "<string>",
            "chosenOption": "<string>",
            "selectedOptions": [
              "<string>"
            ],
            "score": 123,
            "clicks": [
              {
                "number": 123,
                "xCoord": 123,
                "yCoord": 123
              }
            ],
            "ranking": [
              {
                "rank": 123,
                "option": "<string>"
              }
            ],
            "media": "<string>",
            "mediaTranscription": "<string>",
            "matchup": {
              "option1": "<string>",
              "option2": "<string>"
            },
            "respondent": [
              {
                "trait": "<string>",
                "value": "<string>"
              }
            ]
          }
        ],
        "ai": {}
      }
    ]
  },
  "cost": {
    "amount": 123,
    "balance": 123,
    "currency": "<string>",
    "canPayWithBalance": true
  }
}

Documentation Index

Fetch the complete documentation index at: https://www.pickfu.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

OAuth2 access token obtained via the authorization flow. Include in the Authorization header as: Bearer {access_token}

Body

application/json
questions
object[]
required

List of questions for the survey

Minimum array length: 1
name
string

Survey name (1-255 characters, trimmed)

Required string length: 1 - 255
projectId

Project GUID (string) or numeric ID to associate with the survey, or null to leave unassigned. Mutually exclusive with projects.

projects
(string | number)[]

Project GUIDs (or numeric IDs) to associate the survey with. Mutually exclusive with projectId.

Maximum array length: 50
tags
object[]

Tags to attach. Each item has either id (existing tag) or name (find-or-create).

Maximum array length: 10
targeting
string[]

Demographic targeting traits

reporting
string[]

Reporting breakdown traits

country
string

Two-letter country code (e.g. US)

sampleSize
string

Number of respondents (e.g. "15", "30", "50", "75", "100", "200", "300", "500")

surveyIntent
string

Original intent of the survey as interpreted by AI (max 255 characters)

Maximum string length: 255
isMiniPoll
boolean

Whether to create this survey as a daily mini-poll

Response

Default Response

success
boolean
data
object

Full survey data including questions, options, and metadata

cost
object

Cost information for the survey in USD