> ## 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. # Publish survey > Publishes a draft survey and begins collecting responses from the target audience. ### Prerequisites - Survey must be in `unpublished` (draft) status - Account must have sufficient credits - All required fields must be complete (at least one question with options) After publishing, the survey status changes to `pending` or `in-progress` and credits are deducted from your account. ## OpenAPI ````yaml /api-reference/openapi.json post /surveys/{id}/publish openapi: 3.1.0 info: title: PickFu API version: 1.0.0 description: >- The PickFu API enables programmatic access to create surveys, retrieve results, and integrate PickFu into your workflows. ## Overview PickFu helps you get instant consumer feedback through surveys. With the API, you can: - Create surveys programmatically - Retrieve survey results and respondent data - Target specific audiences with demographic traits - Integrate PickFu into your product development workflow ## Rate Limits Selected endpoints (currently the CSV export endpoints) enforce per-caller rate limits and return `429 Too Many Requests` when exceeded. See each endpoint description for its specific budget. ## Authentication All API requests require a Bearer token — either an API key or an OAuth 2.0 access token. See the [Authentication guide](https://www.pickfu.com/docs/developers/authentication) for details. contact: name: PickFu Support email: support@pickfu.com url: https://www.pickfu.com servers: - url: https://api.pickfu.com/v1 description: Production - url: https://api.pickfu-sandbox.com/v1 description: Sandbox security: - bearerAuth: [] tags: - name: Surveys description: >- Create, retrieve, update, and publish surveys. Surveys are the core resource — each contains one or more questions with answer options. - name: Responses description: >- Retrieve individual responses (answers) for a survey, with pagination and per-question filtering. - name: Tags description: Organize surveys with tags. Tags are scoped to your team/account. - name: Projects description: >- Organize surveys into projects. Projects group related surveys and can be bookmarked or archived. - name: Traits description: >- Audience targeting and reporting traits used to reach specific demographics and segment survey results. - name: Playbooks description: >- Discover and retrieve step-by-step research playbooks. Each playbook is a structured sequence of polls designed for a specific research goal. - name: Help description: Search the PickFu help center for articles and guides. - name: Media description: >- Generate images from text prompts and upload media files to the PickFu CDN. paths: /surveys/{id}/publish: post: tags: - Surveys summary: Publish survey description: >- Publishes a draft survey and begins collecting responses from the target audience. ### Prerequisites - Survey must be in `unpublished` (draft) status - Account must have sufficient credits - All required fields must be complete (at least one question with options) After publishing, the survey status changes to `pending` or `in-progress` and credits are deducted from your account. operationId: publishSurvey parameters: - schema: type: string in: path name: id required: true description: Survey ID responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean data: type: object description: >- Full survey data including questions, options, and metadata properties: id: type: string description: Unique survey GUID name: type: string nullable: true description: Survey name/title country: type: string description: Two-letter country code (e.g. US, GB) sampleSize: type: number description: Number of respondents requested numResponses: type: number nullable: true description: Number of responses collected so far status: type: string description: >- Survey status: unpublished, in-progress, completed, or archived (deleted is also possible here for soft-deleted surveys, which the list endpoint excludes). Same vocabulary as the list endpoint — a survey always has the identical status string on both. targeting: type: array items: type: string description: >- Array of targeting trait permalinks applied to this survey reporting: type: array items: type: string description: >- Array of reporting trait permalinks for demographic breakdowns reportingDefaultsApplied: type: array items: type: string description: >- Reporting trait permalinks that were auto-injected as free defaults (based on plan level and country), not explicitly requested by the caller tags: type: array description: Tags associated with the survey items: type: object required: - id - name properties: id: type: string description: Opaque tag identifier (tag_<32-hex>) name: type: string description: Tag name projects: type: array description: Projects the survey belongs to items: type: object required: - id - name properties: id: type: string description: Project GUID name: type: string description: Project name surveyUrl: type: string description: Public URL to view the survey results surveyIntent: type: string description: AI-interpreted intent of the survey questions: type: array description: >- Questions in the survey with options, responses, and AI metadata items: type: object properties: id: type: string description: Question ID (GUID) type: type: string description: >- Question type (head_to_head, ranked, open_ended, click_test, emoji_rating, star_rating, five_second_test, screen_recording, single_select, multi_select, likert) variant: type: string nullable: true description: Question variant for specialized display modes value: type: string description: Question text translation: type: string nullable: true description: Translated question text likertScale: type: string nullable: true enum: - agreement5 - agreement7 - frequency - satisfaction - null description: >- Likert scale preset, returned for likert questions whose meta.columns matches one of the canonical presets. Null for non-likert questions or for likert questions with a custom (non-preset) scale. DEV-3128. options: type: array items: type: object properties: id: type: string description: Option GUID for round-trip updates label: type: string description: Option identifier label (e.g. "Option A") value: oneOf: - type: string - type: array items: type: string description: >- Option content: text string, Cloudinary URL, or array of URLs (image-set) type: type: string description: >- Option data type: text, image, video, product, or image-set translation: type: string nullable: true description: Translated option text product: type: object nullable: true description: >- Product data for product-type options (ASIN mockups) properties: asin: type: string description: Amazon ASIN title: type: string description: Product title price: type: number description: Product price salePrice: type: number nullable: true description: >- Discounted/sale price. null when the product is not on sale. rating: type: number description: Star rating (0-5) reviews: type: number description: Number of reviews image: type: string description: Product image URL imageSetDirection: type: string description: >- Image stack layout direction: horizontal or vertical (image-set options only) mockupType: type: string description: >- Product mockup rendering style: serp or listing (product options only) nullable: true description: Answer options for this question context: type: object nullable: true description: >- Additional context provided with the question (e.g. a product description or image) properties: type: type: string description: Context type (text or media) value: type: string description: Context content translation: type: string nullable: true description: Translated context text results: type: object nullable: true description: >- Aggregated, page-faithful summary of the outcome for this question — the same percentages and ranking shown on the results page. Null for question types without a simple per-option aggregate (open_ended, click_test, likert, five_second_test, screen_recording, round_robin) or before any responses arrive. For ranked questions, `votes` is the final instant-runoff tally the percentage is computed from, and differs from the first-choice count shown beside each option on the page; the winner exceeds 50%. properties: totalResponses: type: number description: >- Number of valid responses the percentages are computed against winningOptionId: type: string nullable: true description: >- GUID of the winning option, or null on a tie / before a winner is decided averageScore: type: number description: >- Average rating, returned for rating questions only (emoji_rating, star_rating) options: type: array description: >- Per-option results, ordered by rank (winner first) items: type: object properties: id: type: string description: Option GUID label: type: string nullable: true description: Option label (e.g. "A") votes: type: number description: >- Vote count; the final instant-runoff tally for ranked questions percentage: type: number description: >- round(votes / totalResponses * 100), matching the results page rank: type: number nullable: true description: Final placement (1 = winner) isWinner: type: boolean description: Whether this option is the winner responses: type: array description: Respondent answers for this question items: type: object properties: id: type: string description: Response ID pinned: type: boolean description: Whether the response is pinned explanation: type: string nullable: true description: Written explanation from the respondent translation: type: string nullable: true description: Translated explanation text chosenOption: type: string nullable: true description: >- Label of the option chosen by the respondent selectedOptions: type: array nullable: true description: >- Labels of options selected by the respondent for multi-select questions items: type: string score: type: number nullable: true description: >- Rating score (for emoji_rating, star_rating question types) clicks: type: array nullable: true description: Click coordinates for click_test questions items: type: object properties: number: type: number description: Click sequence number xCoord: type: number description: X coordinate of the click yCoord: type: number description: Y coordinate of the click ranking: type: array nullable: true description: >- Respondent's ranking of options for ranked question types. Each entry pairs a rank (1 = top pick) with the option label. items: type: object properties: rank: type: number description: >- Rank position (1 = respondent's top pick) option: type: string nullable: true description: Option label at this rank media: type: string nullable: true description: >- Media URL (for screen_recording question types) mediaTranscription: type: string nullable: true description: Transcription of the recorded media matchup: type: object nullable: true description: >- Head-to-head matchup pairing shown to the respondent properties: option1: type: string description: First option in the matchup option2: type: string description: Second option in the matchup statements: type: array nullable: true description: >- Per-statement responses for likert question types. Each entry pairs a statement with the numeric value the respondent picked on the configured scale. DEV-3149. items: type: object properties: id: type: string description: >- GUID of the statement (the question option) statement: type: string nullable: true description: Statement text value: type: number description: >- Numeric value the respondent picked on the Likert scale (1..N for the configured scale) respondent: type: array description: Demographic traits of the respondent items: type: object properties: trait: type: string description: Trait category name value: type: string description: Trait value ai: type: object description: >- AI-generated metadata such as summaries and key themes for this question additionalProperties: type: string cost: type: object description: Cost information for the survey properties: amount: type: number description: Poll cost in dollars balance: type: number description: Credit balance in dollars currency: type: string description: Currency code (USD) canPayWithBalance: type: boolean description: Whether balance covers the cost quotedCreditsCost: type: number description: >- Post-discount cost in credits, after free credits applied (1 credit = $2 USD) creditsCostSubtotal: type: number description: Pre-discount cost in credits (1 credit = $2 USD) discounts: type: array description: >- Credit-side discount line items, each entry is [label, amountInCredits]. Amounts are denominated in credits so they subtract directly from creditsCostSubtotal items: type: array items: type: string discountsMoney: type: array description: >- Dollar-side discount line items, each entry is [label, formattedDollarAmount] (e.g. "$20.08") items: type: array items: type: string planRequired: type: - 'null' - string description: >- Plan tier required for current survey configuration, or null if the current plan is sufficient '400': description: Default Response content: application/json: schema: type: object properties: statusCode: type: number error: type: string message: type: string '401': description: Default Response content: application/json: schema: type: string '403': description: Default Response content: application/json: schema: type: string '404': description: Default Response content: application/json: schema: type: string components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- OAuth2 access token obtained via the authorization flow. Include in the Authorization header as: `Bearer {access_token}` ````