How can we help you?

Advanced documentation search

Survey Builder API Reference

Product: FeraSurvey Topic: API Versions: Applies to all documented versions Current
Written by user
Updated

Survey Builder

Load and save the complete visual-editor model for a survey.

Product: FeraSurvey
Audience: Application developers
Editorial status: Review Required

Review required before publication

The connected feradel.survey.api repository contains only an initial .gitignore commit. This reference documents the contract observed in the FeraSurvey dashboard client. Verify all routes, headers, schemas, status codes, and error responses against the deployed API before publication or external reliance.

The builder model

The builder model contains the information required to display and edit a survey in the visual editor. It includes the survey configuration, system settings, sections, questions, and identifiers for deleted items.

Use the builder endpoints when an application needs to:

  • Open an existing survey in the visual editor.
  • Save the complete editor state.
  • Add, update, reorder, or remove sections and questions.
  • Preserve information needed by the server to reconcile deletions.
  • Configure question behavior, collection links, and uploads.

The observed endpoints are:

GET /api/surveys/{surveyId}/builder
PUT /api/surveys/{surveyId}/builder

These endpoints operate on the complete builder model. They are not documented as partial-update endpoints.

Retrieve the builder model

GET /api/surveys/{surveyId}/builder

Retrieves the complete visual-editor model for a survey.

Parameters

Path parameters

surveyId
string
Required

The unique identifier of the survey.

Headers

Send the authentication, instance, correlation, and public-response headers required by the deployed environment.

The precise header names and requirements must be verified against the deployed API.

Returns

Returns the survey’s editor item, including its survey configuration, system settings, sections, and questions.

The authoritative response schema has not yet been verified.

Example request

curl https://{api-base-url}/api/surveys/{surveyId}/builder \
  -H "Authorization: Bearer {accessToken}" \
  -H "Accept: application/json"

Example response

{
  "survey": {},
  "system": {},
  "sections": [
    {
      "questions": [
        {
          "uuid": "9b0b85a4-e642-4a79-89d8-5fb4a190648d",
          "key": "contact_name",
          "typeName": "text",
          "label": "Your name",
          "help": "Enter your full name.",
          "required": true,
          "meta": {},
          "collection": null,
          "upload": false
        }
      ]
    }
  ],
  "deletedSections": [],
  "deletedQuestions": []
}

The example illustrates the observed top-level builder fields and question properties. It is not an authoritative server response.

Update the builder model

PUT /api/surveys/{surveyId}/builder

Replaces or reconciles the complete visual-editor model for a survey.

Send the complete current builder state, including identifiers for sections and questions removed since the model was loaded.

Parameters

Path parameters

surveyId
string
Required

The unique identifier of the survey.

Request body

survey
object
Required

The survey-level configuration displayed or maintained by the editor.

The authoritative properties of this object must be verified against the deployed API.

system
object
Required

System-controlled or editor-level survey settings.

The authoritative properties of this object must be verified against the deployed API.

sections
array of objects
Required

The ordered sections currently belonging to the survey. Sections contain the survey’s questions.

deletedSections
array
Required

The identifiers or deleted section records that the server should remove or reconcile.

The required item shape must be verified.

deletedQuestions
array
Required

The identifiers or deleted question records that the server should remove or reconcile.

The required item shape must be verified.

Question attributes

Questions within sections include the following observed properties.

uuid
string
Required

A UUID that identifies the question independently of its display order.

key
string
Required

The stable application-facing key used to identify the answer associated with the question. Keys should be unique within the scope enforced by the server.

typeName
string
Required

The registered question type. The server should reject unsupported question types.

label
string
Required

The question text displayed to the respondent.

help
string or null
Optional

Supporting instructions or explanatory text displayed with the question.

required
boolean
Required

Whether the respondent must answer the question before completing the applicable survey step.

meta
object
Required

Type-specific question configuration. Its permitted properties depend on typeName.

collection
object, string, or null
Optional

A reference to a linked collection used by the question. The precise wire format must be verified against the deployed API.

upload
boolean
Required

Whether the question uses or permits file-upload behavior.

Example request

curl https://{api-base-url}/api/surveys/{surveyId}/builder \
  -X PUT \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "survey": {},
    "system": {},
    "sections": [
      {
        "questions": [
          {
            "uuid": "9b0b85a4-e642-4a79-89d8-5fb4a190648d",
            "key": "contact_name",
            "typeName": "text",
            "label": "Your name",
            "help": "Enter your full name.",
            "required": true,
            "meta": {},
            "collection": null,
            "upload": false
          }
        ]
      }
    ],
    "deletedSections": [],
    "deletedQuestions": []
  }'

Returns

Returns the saved builder model or another success representation defined by the deployed API.

The response body and success status code must be verified before publication.

Example response

{
  "survey": {},
  "system": {},
  "sections": [
    {
      "questions": [
        {
          "uuid": "9b0b85a4-e642-4a79-89d8-5fb4a190648d",
          "key": "contact_name",
          "typeName": "text",
          "label": "Your name",
          "help": "Enter your full name.",
          "required": true,
          "meta": {},
          "collection": null,
          "upload": false
        }
      ]
    }
  ],
  "deletedSections": [],
  "deletedQuestions": []
}

This response is illustrative and must be replaced with a response captured from the deployed API.

Validation

The server should validate the complete builder model before saving it.

At a minimum, validation should cover:

  • The authenticated principal’s access to the survey.
  • The survey’s ownership by the applicable user, account, or instance.
  • The uniqueness and permitted format of question keys.
  • The validity of section and question identifiers.
  • The existence and accessibility of linked collections.
  • The compatibility of collection links with the applicable question type.
  • The availability of each typeName.
  • The validity of each question’s meta configuration.
  • The validity of upload-enabled questions.
  • The consistency of active and deleted records.
  • The supported builder schema version.

The deployed API’s actual validation rules and error format remain to be verified.

Complete-model updates

Treat PUT /api/surveys/{surveyId}/builder as a complete-model operation unless the deployed API establishes different behavior.

Applications should:

  1. Retrieve the current builder model.
  2. Preserve unmodified properties returned by the server.
  3. Apply edits to the local model.
  4. Add removed items to deletedSections or deletedQuestions, as applicable.
  5. Send the complete updated model in a single PUT request.
  6. Replace the local model with the authoritative model returned by the server, if one is returned.

Do not assume that omitted sections, questions, or settings remain unchanged.

Concurrent updates

The observed dashboard contract does not establish how the API detects concurrent edits.

Before publication, determine whether the deployed API uses:

  • Entity tags and If-Match.
  • A model version or revision property.
  • Updated timestamps.
  • Last-write-wins behavior.
  • A dedicated conflict response.

If the server supports optimistic concurrency, document the required request value and the conflict-recovery procedure.

Errors

The deployed error schema and status codes must be captured and documented. Expected categories include:

Status Meaning
400 The request is malformed or uses an unsupported builder schema.
401 Authentication is missing, invalid, or expired.
403 The caller cannot access or modify the survey.
404 The survey or a required linked resource does not exist.
409 The update conflicts with the current builder state or another unique value.
422 The builder model fails validation.
500 The server could not retrieve or save the builder model.

These mappings are provisional and must be verified against the deployed API.

Validation errors

Validation responses should identify the affected property whenever possible.

Potential validation failures include:

  • Duplicate question keys.
  • Unsupported question types.
  • Invalid question metadata.
  • Invalid UUIDs.
  • Missing linked collections.
  • Inaccessible linked collections.
  • Invalid deletion references.
  • Unsupported schema versions.

Do not publish a sample error object until its structure has been captured from the deployed service or defined in an authoritative OpenAPI contract.

Idempotency and retries

The observed client contract does not establish whether builder updates support idempotency keys.

Do not automatically retry a PUT request after an indeterminate network failure unless the deployed API confirms that repeating the request is safe. Before publication, document:

  • Whether identical PUT requests are idempotent.
  • Whether the API accepts an idempotency header.
  • How duplicate requests are detected.
  • How applications should recover after a timeout.
  • Whether a subsequent GET can confirm the saved state.

Schema versioning

The server should validate the builder schema version before accepting an update. The observed contract does not establish where the version is transmitted.

Verify whether the version appears in:

  • The request body.
  • An HTTP header.
  • The survey or system object.
  • The endpoint path.
  • The authenticated instance configuration.

Document the supported versions and migration behavior before external publication.

Troubleshooting

The deployed route differs

Treat the deployed API as authoritative. Reconcile the dashboard client, this article, and the OpenAPI contract so they describe the same route.

The response shape is undocumented

Keep this article marked Review Required until an authoritative server schema exists or representative responses have been captured from the deployed API.

A save request removes unexpected data

Confirm that the client sends the complete builder model. Do not omit unchanged sections, questions, survey settings, or system settings from a complete-model PUT.

A question key is rejected

Confirm that the key is unique within the server-defined scope and satisfies any naming restrictions imposed by the deployed API.

A linked collection is rejected

Confirm that the collection exists, belongs to an accessible account or instance, and is supported by the selected question type.

A save request returns a conflict

Reload the current builder model before reapplying the user’s changes. Do not overwrite a newer model until the API’s concurrency behavior has been verified.

Publication checklist

Before removing the Review Required designation:

  1. Verify the deployed base URL.
  2. Verify both endpoint paths and supported HTTP methods.
  3. Record all required authentication and instance headers.
  4. Determine whether correlation or public-response headers are required.
  5. Capture a representative successful GET response.
  6. Capture a representative successful PUT request and response.
  7. Capture validation, conflict, authentication, authorization, not-found, and server-failure responses.
  8. Confirm the complete schemas for survey, system, sections, questions, and deletion records.
  9. Confirm ownership and linked-collection validation.
  10. Confirm concurrency, idempotency, retry, and schema-version behavior.
  11. Update the OpenAPI contract.
  12. Verify the finished article against the deployed API.

Related documentation

Source review

Source reviewed: feradelinc/feradel.survey.client at 4ff3d795858f and feradelinc/feradel.survey.api at 00a4362332ce

Source area: src/utils/api/index.js; src/views/secure/editor/index.js; API repository placeholder

The connected API repository contains only an initial .gitignore commit. The route contract in this draft is inferred from the dashboard API client and must be verified against the deployed server or a future OpenAPI specification.