---
title: "Reorder Questions"
method: PUT
path: "/voice/questions/reorder"
tags: ["Voice Agent Questions"]
---

# Reorder Questions

`PUT /voice/questions/reorder`

## Request

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

### Reorder Questions

Requires the OWNER or ADMIN role. Bulk-writes the order field on each listed question, then returns the agent's full question list in its new order. Entries for a fieldId that does not belong to the given agentId are silently skipped (no error).

## Request body

- object
  - `agentId` string, required: Required.
  - `fieldOrders` object[], required: Required. The new order for some or all of the agent's questions; each entry's order value is written directly (not resequenced).
    - `fieldId` string, required
    - `order` number, required

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `fields` 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

- `403`: Caller's role is not OWNER or ADMIN
- `404`: Agent 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)