Skip to main content
Templates are PickFu product combos: ready-made single-question polls written by PickFu, each with a fixed price per response and fixed limits on sample size, country, options, and audience. Use a template when you want a proven poll at the template’s price instead of writing your own questions. v2 serves the public templates plus any made for the selected owner. A team key sees its team’s templates, and a personal account sees its own. Saved team templates from the PickFu app aren’t served by the API. The flow has three steps:
1

Find a template

GET /v2/templates lists templates you can use.
2

Read its details

GET /v2/templates/{id} returns the question, its {{name}} blanks, option slots, audience, and constraints.
3

Create a draft

POST /v2/surveys with a template block creates a draft priced at the template’s rate. Publish it with POST /v2/surveys/{id}/publish as usual.
Template ids look like cmb_<slug>, for example cmb_business-name-test.

List templates

GET /v2/templates requires the read scope. Templates made for your account come first, then the rest by position. The response uses cursor pagination.
string
Case-insensitive text matched against template names, descriptions, and features. Up to 255 characters.
string
default:"all"
mine returns templates made for the selected owner. public returns the rest. all returns both.
string
Only templates that can run in this country, for example US.
string
Only templates that accept this kind of option: text, image, video, url, product, image-set, or audio.
integer
default:"20"
Page size, 1–100.
string
The nextCursor from a previous response. Send the same filters and limit with it.
Each entry includes:
  • id: the cmb_<slug> template id.
  • access: mine when the template was made for your account, otherwise public.
  • questionTypes and optionCount: the question types and the { min, max } option count the template allows.
  • pricePerResponse: the price per respondent in US dollars at the template’s default country.
  • url: opens the template in the PickFu survey builder.

Get a template

GET /v2/templates/{id} requires the read scope and returns everything a create needs. An unknown id and another account’s template both return 404 resource_missing with param set to "id".
The detail response adds these fields to the list entry:

Create a draft from a template

POST /v2/surveys requires the write scope. Send a template block instead of questions. Send exactly one of the two.
string
required
The cmb_<slug> id from GET /v2/templates.
object
One value per {{name}} blank in the template’s question, keyed by the blank’s name. Every blank must be filled.
string
Replaces the question of a template without blanks. Required when the template has no question. Up to 255 characters. Templates with blanks take blanks instead.
object
Context shown with the question, as text or mediaUrl (one, not both). Only for templates that take context.
object[]
The question’s options, in the same shape as a question’s options. Up to 8. Omit to use the template’s preset values when it has one for every slot.
  • PickFu picks the question type from the template. Where a template offers both, two options or fewer run head_to_head and three or more run ranked.
  • When you omit sampleSize, country, name, or targeting, the draft uses the template’s values. To change the audience, send the full targeting list and keep its preset values.
  • You can’t send reporting, because a template’s reporting traits are fixed.
  • The template block is create-only. It can’t be combined with questions, isMiniPoll: true, or responseSource: "own".
The response is the draft survey with a cost quote priced at the template’s rate. The API discount doesn’t apply to template drafts. Edit the draft later with PATCH /v2/surveys/{id} using questions and the ids from the response. Every edit must stay within the template’s limits. POST /v2/surveys/{id}/publish accepts template drafts and charges the template price. See Publishing and payments.

The template field on surveys

Every v2 survey carries a template field, or null when it wasn’t made from a template.
  • GET /v2/surveys/{id} and other full survey reads return { id, name, constraints }.
  • Items in GET /v2/surveys return { id, name }.
id is null when the template can no longer be read.

Template errors

Template rejections use the standard v2 error envelope with COMBO_* or TEMPLATE_* codes. PickFu writes nothing when it rejects a template request. A draft outside the template’s limits returns 422. The error.violations array lists every violation with its code, param, message, allowed value, and received value. allowed can be a list of values or a { min, max } range.
A missing blank returns 422 TEMPLATE_BLANKS_UNFILLED with param set to "template.blanks" and an error.blanks array of { name, placeholder } entries still to fill. Publish can also return 422 with a COMBO_* code if the draft no longer meets the template’s limits. Nothing is charged.