---
title: "Create Question Template"
method: POST
path: "/voice/question-templates"
tags: ["Voice Agent Questions"]
---

# Create Question Template

`POST /voice/question-templates`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/question-templates`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### Create Question Template

Requires the OWNER or ADMIN role. Creates a company-scoped template -- the "custom question" a user names themselves rather than picking from Speak's shared library. The server stamps companyId and forces isSystemTemplate to false, so this template is only ever visible to your company.

## Request body

- object
  - `name` string, required: Required.
  - `description` string, required: Required.
  - `category` 'contact' | 'booking' | 'qualification' | 'payment' | 'custom', required: Required.
  - `fieldType` 'email' | 'phone' | 'date' | 'time' | 'datetime' | 'text' | 'number' | 'boolean' | 'choice' | 'url', required: Required.
  - `defaultConfig` object, required: Required on create. displayLabel and question are both required within this object.
    - `displayLabel` string
    - `question` string: The prompt text the agent speaks to ask this. Renamed from promptText.
    - `confirmationText` string
    - `validationPrompt` string
    - `validation` object
      - `pattern` string
      - `minLength` number
      - `maxLength` number
      - `min` number
      - `max` number
      - `allowedValues` string[]
  - `isPublic` boolean
  - `tags` string[]

## Response `201`

Created

- object
  - `status` 'success'
  - `data` object
    - `template` object
      - `_id` string: MongoDB document id, included because every document has one; use templateId to identify it.
      - `templateId` string: Server-generated UUID. Immutable.
      - `userId` string, nullable: Id of the user who created this template. Absent on a system template.
      - `name` string: Required on create.
      - `description` string: Required on create.
      - `category` 'contact' | 'booking' | 'qualification' | 'payment' | 'custom': Required on create.
      - `fieldType` 'email' | 'phone' | 'date' | 'time' | 'datetime' | 'text' | 'number' | 'boolean' | 'choice' | 'url': Required on create.
      - `defaultConfig` object: Required on create. displayLabel and question are both required within this object.
        - `displayLabel` string
        - `question` string: The prompt text the agent speaks to ask this. Renamed from promptText.
        - `confirmationText` string
        - `validationPrompt` string
        - `validation` object
          - `pattern` string
          - `minLength` number
          - `maxLength` number
          - `min` number
          - `max` number
          - `allowedValues` string[]
      - `isSystemTemplate` boolean: Always false for a template your company creates. Not settable directly.
      - `isPublic` boolean: Defaults to false.
      - `tags` string[]
      - `usageCount` integer: Incremented when a question is created from this template, decremented when that question is deleted. Not settable directly.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

## Other responses

- `400`: Validation failed
- `403`: Caller's role is not OWNER or ADMIN

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)