V3 Surveys

Set survey block order

Changed on

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

Request

  • Base URL
    https://app.formbricks.com
  • URL
    https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order
  • Auth
    • API key in cookie next-auth.session-token
    • or API key in header x-api-key
    • or HTTP bearer

Path parameters

surveyIdstring cuid2 required

Survey identifier.

Request body

orderstring[] 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.

expectedUpdatedAtstring 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

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

Changes

    • warning

      added the new row enum value to the /////////// response property for the response status

    • warning

      added the new row enum value to the /////////// response property for the response status

    • breaking

      added subschema #5: SurveyInteractionFilter to the ///////////// response property oneOf list for the response status