> ## Documentation Index
> Fetch the complete documentation index at: https://www.pickfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> List and read PickFu templates on v2, create a draft survey from a template, and handle template limit errors.

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](https://www.pickfu.com/docs/api-reference/v2/pagination.md).

**query** `string`

Case-insensitive text matched against template names, descriptions, and features. Up to 255 characters.

**access** `string` (default: all)

`mine` returns templates made for the selected owner. `public` returns the rest. `all` returns both.

**country** `string`

Only templates that can run in this country, for example `US`.

**optionType** `string`

Only templates that accept this kind of option: `text`, `image`, `video`, `url`, `product`, `image-set`, or `audio`.

**limit** `integer` (default: 20)

Page size, 1–100.

**cursor** `string`

The `nextCursor` from a previous response. Send the same filters and `limit` with it.

```bash theme={null}
curl "https://api.pickfu.com/v2/templates?query=name&country=US" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "object": "template",
      "id": "cmb_business-name-test",
      "name": "Business name test",
      "description": "Find the business name your customers prefer.",
      "access": "public",
      "questionTypes": ["head_to_head", "ranked"],
      "optionCount": { "min": 2, "max": 8 },
      "pricePerResponse": 1,
      "url": "https://app.pickfu.com/..."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

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"`.

```bash theme={null}
curl https://api.pickfu.com/v2/templates/cmb_business-name-test \
  -H "Authorization: Bearer sk_live_your_key_here"
```

The detail response adds these fields to the list entry:

| Field | Description |
| - | - |
| `originalPricePerResponse` | Price per respondent without the template, or `null`. |
| `question` | `text` of the question, where `{{name}}` marks a blank, and `blanks`, a list of `{ name, placeholder }`. |
| `constraints` | The limits a draft must meet to publish at the template's price: `questionTypes`, `optionTypes`, `optionCount`, `sampleSizes`, `defaultSampleSize`, `countries`, and `defaultCountry`. Sample sizes are integers. |
| `optionSlots` | One entry per option with `label`, `helpText`, `kind`, and `presetValue`. |
| `audience` | `preset` trait values, whether `presetRequired`, `choosable` traits, the number of `openSlots` for other traits, and `blocked` traits. |
| `reporting` | The fixed reporting traits. |
| `context` | Help for the optional context shown with the question, or `null` when the template doesn't take context. |
| `exampleUrl` | An example of the template's results, or `null`. |

## 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.

```bash theme={null}
curl -X POST https://api.pickfu.com/v2/surveys \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "id": "cmb_business-name-test",
      "blanks": { "madlib_business_description": "a neighborhood coffee roastery" },
      "options": [
        { "value": "Ember & Bean" },
        { "value": "Corner Roast Co." },
        { "value": "Daybreak Roasters" }
      ]
    },
    "sampleSize": 50
  }'
```

**template.id** `string` *required*

The `cmb_<slug>` id from `GET /v2/templates`.

**template.blanks** `object`

One value per `{{name}}` blank in the template's question, keyed by the blank's name. Every blank must be filled.

**template.prompt** `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.

**template.context** `object`

Context shown with the question, as `text` or `mediaUrl` (one, not both). Only for templates that take context.

**template.options** `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](https://www.pickfu.com/docs/api-reference/v2/payments.md).

## 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.

```json theme={null}
{
  "object": "survey",
  "id": "srv_01J9C2VZH8...",
  "status": "unpublished",
  "template": {
    "id": "cmb_business-name-test",
    "name": "Business name test",
    "constraints": {
      "questionTypes": ["head_to_head", "ranked"],
      "optionTypes": ["text"],
      "optionCount": { "min": 2, "max": 8 },
      "sampleSizes": [50, 100],
      "defaultSampleSize": 50,
      "countries": ["US"],
      "defaultCountry": "US"
    }
  }
}
```

## Template errors

Template rejections use the standard [v2 error envelope](https://www.pickfu.com/docs/api-reference/v2/errors.md) 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.

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "COMBO_OPTION_COUNT",
    "param": "template.options",
    "message": "Template \"Business name test\" takes exactly 2 options; you sent 3. It offers sample sizes 50, 100; you sent 75.",
    "violations": [
      {
        "code": "COMBO_OPTION_COUNT",
        "param": "template.options",
        "message": "Template \"Business name test\" takes exactly 2 options; you sent 3.",
        "allowed": { "min": 2, "max": 2 },
        "received": 3
      },
      {
        "code": "COMBO_RESPONSE_COUNT",
        "param": "sampleSize",
        "message": "Template \"Business name test\" offers sample sizes 50, 100; you sent 75.",
        "allowed": [50, 100],
        "received": 75
      }
    ]
  },
  "requestId": "req_01J9C2VZH8..."
}
```

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.

| Status | Code | Cause |
| - | - | - |
| `400` | `TEMPLATE_WITH_QUESTIONS` | Both `template` and `questions` were sent. |
| `400` | `TEMPLATE_REPORTING_FIXED` | `reporting` was sent with a template. |
| `400` | `TEMPLATE_WITH_MINI_POLL` | `isMiniPoll` was sent with a template. |
| `400` | `TEMPLATE_WITH_OWN_AUDIENCE` | `responseSource: "own"` was sent with a template. |
| `404` | `resource_missing` | The template id is unknown or belongs to another account. |
| `422` | `COMBO_*` | The draft is outside the template's limits. See `error.violations`. |
| `422` | `TEMPLATE_BLANKS_UNFILLED` | A `{{name}}` blank wasn't filled. See `error.blanks`. |

Publish can also return `422` with a `COMBO_*` code if the draft no longer meets the template's limits. Nothing is charged.


## Related topics

- [List mockup templates](https://www.pickfu.com/docs/api-reference/surveys/list-mockup-templates.md)
- [How do I build a survey from a template?](https://www.pickfu.com/help/how-do-i-build-a-poll-from-a-template.md)
- [PickFu consumer insights template for Grok Bot](https://www.pickfu.com/docs/integrations/grok-bot.md)
- [PickFu MCP server for Claude, Cursor, and ChatGPT](https://www.pickfu.com/docs/integrations/mcp-server.md)
- [How to build a PickFu survey](https://www.pickfu.com/help/how-to-build-a-pickfu-poll-or-survey.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.