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.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.
Case-insensitive text matched against template names, descriptions, and features. Up to 255 characters.
mine returns templates made for the selected owner. public returns the rest. all returns both.Only templates that accept this kind of option:
text, image, video, url, product, image-set, or audio.id: thecmb_<slug>template id.access:minewhen the template was made for your account, otherwisepublic.questionTypesandoptionCount: 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".
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.
One value per
{{name}} blank in the template’s question, keyed by the blank’s name. Every blank must be filled.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.Context shown with the question, as
text or mediaUrl (one, not both). Only for templates that take context.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_headand three or more runranked. - When you omit
sampleSize,country,name, ortargeting, the draft uses the template’s values. To change the audience, send the fulltargetinglist and keep its preset values. - You can’t send
reporting, because a template’s reporting traits are fixed. - The
templateblock is create-only. It can’t be combined withquestions,isMiniPoll: true, orresponseSource: "own".
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/surveysreturn{ id, name }.
id is null when the template can no longer be read.
Template errors
Template rejections use the standard v2 error envelope withCOMBO_* 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.
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.