Set survey block order

Replaces the order of a survey’s blocks. The body lists every current block id exactly once, in the order you want; block content is untouched.

Idempotent: the same order always yields the same survey, and an order that already matches performs no write at all, so updatedAt does not move and other callers’ preconditions stay valid. A stale expectedUpdatedAt is still rejected with 409 on that path — the precondition is evaluated before the method, so a no-op outcome never reports success to a stale caller. Because the list must be a permutation, a dropped or duplicated block is rejected rather than silently applied — the failure mode that resending the whole blocks array cannot catch.

Pass expectedUpdatedAt (the updatedAt from your last read) to make the write conditional; see the 409 response. Session cookie or x-api-key.

PUT /api/v3/surveys/{surveyId}/blocks/order

Set survey block order

cURL

curl --request PUT \
  --url https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order \
  --header 'Content-Type: application/json' \
  --cookie next-auth.session-token= \
  --data '
{
  "order": [
    "b4h8s2d6f0g3j5k7l9z1x3c5",
    "k1p9wq2m4x7c3v8b5n6t0j2r",
    "n7m4q8w2e6r0t3y5u1i9o2p4"
  ],
  "expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
'

200

{
  "data": {
    "id": "<string>",
    "workspaceId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "type": "link",
    "status": "draft",
    "metadata": {
      "title": {
        "en-US": "What should we improve?",
        "de-DE": "Was sollten wir verbessern?"
      },
      "description": {
        "en-US": "What should we improve?",
        "de-DE": "Was sollten wir verbessern?"
      }
    },
    "defaultLanguage": "<string>",
    "languages": [
      {
        "code": "en-US",
        "default": true,
        "enabled": true,
        "alias": "english"
      }
    ],
    "showLanguageSwitch": true,
    "autoSelectLanguage": true,
    "welcomeCard": {
      "enabled": true,
      "headline": {
        "en-US": "What should we improve?",
        "de-DE": "Was sollten wir verbessern?"
      },
      "subheader": {
        "en-US": "What should we improve?",
        "de-DE": "Was sollten wir verbessern?"
      },
      "buttonLabel": {
        "en-US": "What should we improve?",
        "de-DE": "Was sollten wir verbessern?"
      },
      "fileUrl": "<string>",
      "videoUrl": "<string>",
      "timeToFinish": true,
      "showResponseCount": true
    },
    "blocks": [
      {
        "id": "<string>",
        "name": "<string>",
        "elements": [
          {
            "id": "<string>",
            "type": "openText",
            "headline": {
              "en-US": "What should we improve?",
              "de-DE": "Was sollten wir verbessern?"
            },
            "required": true,
            "subheader": {
              "en-US": "What should we improve?",
              "de-DE": "Was sollten wir verbessern?"
            },
            "imageUrl": "<string>",
            "imageAltText": {
              "en-US": "What should we improve?",
              "de-DE": "Was sollten wir verbessern?"
            },
            "videoUrl": "<string>",
            "isDraft": true,
            "placeholder": {
              "en-US": "What should we improve?",
              "de-DE": "Was sollten wir verbessern?"
            },
            "longAnswer": true,
            "inputType": "text",
            "insightsEnabled": false,
            "charLimit": {
              "enabled": false,
              "min": 123,
              "max": 123
            },
            "validation": {
              "rules": [
                {
                  "id": "<string>",
                  "type": "minLength",
                  "params": {},
                  "field": "addressLine1"
                }
              ],
              "logic": "and"
            }
          }
        ],
        "logic": [
          {
            "id": "<string>",
            "conditions": {
              "id": "<string>",
              "connector": "and",
              "conditions": [
                {
                  "id": "<string>",
                  "leftOperand": {
                    "type": "element",
                    "value": "<string>",
                    "meta": {}
                  },
                  "operator": "equals",
                  "rightOperand": {
                    "type": "static",
                    "value": "<string>"
                  }
                }
              ]
            },
            "actions": [
              {
                "id": "<string>",
                "objective": "calculate",
                "variableId": "<string>",
                "operator": "assign",
                "value": {
                  "type": "static",
                  "value": "<string>"
                }
              }
            ]
          }
        ],
        "logicFallback": "<string>",
        "buttonLabel": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        },
        "backButtonLabel": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        }
      }
    ],
    "endings": [
      {
        "id": "<string>",
        "type": "endScreen",
        "headline": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        },
        "subheader": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        },
        "buttonLabel": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        },
        "buttonLink": "<string>",
        "imageUrl": "<string>",
        "imageAltText": {
          "en-US": "What should we improve?",
          "de-DE": "Was sollten wir verbessern?"
        },
        "videoUrl": "<string>",
        "hideDefaultIcon": true
      }
    ],
    "hiddenFields": {
      "enabled": true,
      "fieldIds": [
        "<string>"
      ]
    },
    "variables": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "number",
        "value": 123
      }
    ],
    "customCss": {
      "light": "<string>",
      "dark": "<string>"
    },
    "visibility": "restricted",
    "owner": {
      "name": "<string>"
    },
    "access": {
      "via": "workspace",
      "canManageVisibility": true
    },
    "distribution": {
      "displayOption": "displaySome",
      "displayLimit": 3,
      "displayPercentage": null,
      "recontactDays": 7,
      "autoClose": null,
      "autoComplete": null,
      "delay": 0,
      "triggers": [
        {
          "actionClassId": "clyy1234567890123456789012"
        }
      ]
    },
    "targeting": {
      "filters": [
        {
          "id": "<string>",
          "connector": "and",
          "resource": {
            "id": "<string>",
            "root": {
              "type": "attribute",
              "contactAttributeKey": "<string>"
            },
            "qualifier": {
              "operator": "lessThan"
            },
            "value": "<string>"
          }
        }
      ]
    }
  }
}

Authorizations

sessionAuthapiKeyAuthbearerAuth

next-auth.session-token · string · cookie · required

NextAuth session JWT cookie. Development: often next-auth.session-token. Production (HTTPS): often __Secure-next-auth.session-token. Send the cookie your browser receives after sign-in.

Path Parameters

surveyId · string<cuid2> · required

Survey identifier.

Body

application/json

order · string[] · required

Every current block id, exactly once, in the desired order. Ids are trimmed before use, so an id that is empty or whitespace-only is a 400, as is a list of more than 1000 ids. A missing, unknown or repeated id is a 422 — repeats are reported as duplicate_identifier rather than rejected by the schema, so the response names the offending entry, and a dropped block cannot pass unnoticed, which is what makes this safer than resending the blocks.

Required array length: 1 - 1000 elements

Required string length: 1 - 128

expectedUpdatedAt · string<date-time>

Optimistic-concurrency precondition: the survey's updatedAt from your last read. If the survey changed since, the write is rejected with 409.

Response

200

application/json

Order applied (or already matching); returns the full survey resource.

data · object · required

The three fields every SurveyListItem and SurveyResource carries, merged into both via allOf. All required, always present.

Show child attributes