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": [
    {
      "type": "head_to_head",
      "prompt": "<string>",
      "context": {
        "text": "<string>",
        "mediaUrl": "<string>"
      },
      "options": [
        {
          "value": "<string>",
          "mediaUrl": "<string>",
          "asin": "<string>",
          "imageSet": [
            "<string>"
          ],
          "imageSetDirection": "vertical",
          "mockup": {
            "type": "serp",
            "image": "<string>",
            "title": "<string>",
            "numRatings": 123,
            "reviewScore": 123,
            "price": 123,
            "currency": "<string>"
          }
        }
      ]
    }
  ],
  "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>"
      }
    ],
    "project": {
      "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>",
            "explanation": "<string>",
            "translation": "<string>",
            "chosenOption": "<string>",
            "score": 123,
            "clicks": [
              {
                "number": 123,
                "xCoord": 123,
                "yCoord": 123
              }
            ],
            "rounds": [
              {
                "number": 123,
                "option": "<string>"
              }
            ],
            "media": "<string>",
            "mediaTranscription": "<string>",
            "matchup": {
              "option1": "<string>",
              "option2": "<string>"
            },
            "respondent": [
              {
                "trait": "<string>",
                "value": "<string>"
              }
            ]
          }
        ],
        "ai": {}
      }
    ]
  }
}

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
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", "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