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

# Create Question

`POST /voice/questions`

## Request

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

### Create Question

Requires the OWNER or ADMIN role. Attaches a question template to an agent. agentId and templateId are both required; both must belong to your company (or, for templateId, be a public system template). Returns 404 if either is not found.

## Request body

- object
  - `agentId` string, required: Required.
  - `templateId` string, required: Required. Must reference a template your company can see (its own, or a system template).
  - `customConfig` object: Agent-level override of the template's defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
    - `displayLabel` string
    - `question` string: The prompt text the agent speaks to ask this question. Renamed from promptText.
    - `confirmationText` string
    - `validationPrompt` string
    - `validation` object
      - `pattern` string
      - `minLength` number
      - `maxLength` number
      - `min` number
      - `max` number
      - `allowedValues` string[]
  - `required` boolean
  - `maxPromptAttempts` number
  - `noResponseBehavior` 'move_to_next_question' | 'end_conversation'
  - `triggerCondition` string
  - `order` number
  - `enabled` boolean
  - `mappedFieldId` string, nullable: Id of an existing company Field to write this question's collected answer onto after each call.

## Response `201`

Created

- object
  - `status` 'success'
  - `data` object
    - `field` object
      - `_id` string: MongoDB document id, included because every document has one; use fieldId to identify it.
      - `fieldId` string: Server-generated UUID. Immutable -- sent in the body on create or update is silently dropped.
      - `companyId` string: Stamped from the caller's authenticated company. Sent in the body is silently dropped.
      - `userId` string: Id of the user who created this question. Sent in the body is silently dropped.
      - `agentId` string: Required on create. Immutable after create -- sent on update is silently dropped.
      - `templateId` string: Required on create. The question template this question is based on. Immutable after create -- sent on update is silently dropped.
      - `customConfig` object: Agent-level override of the template's defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
        - `displayLabel` string
        - `question` string: The prompt text the agent speaks to ask this question. Renamed from promptText.
        - `confirmationText` string
        - `validationPrompt` string
        - `validation` object
          - `pattern` string
          - `minLength` number
          - `maxLength` number
          - `min` number
          - `max` number
          - `allowedValues` string[]
      - `required` boolean: Defaults to false. Agent must collect this before ending the conversation.
      - `maxPromptAttempts` number: Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as "number".
      - `noResponseBehavior` 'move_to_next_question' | 'end_conversation': Defaults to move_to_next_question.
      - `triggerCondition` string
      - `order` number: Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
      - `enabled` boolean: Defaults to true.
      - `mappedFieldId` string, nullable: Id of a general company Field (see the Fields API) this question's collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

## Other responses

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

---

[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)