> ## Documentation Index > Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt > Use this file to discover all available pages before exploring further. # Importing Surveys > Import a survey from a Voxworks JSON survey definition: the Import from platform wizard, Upload new version, the JSON format and the question types it maps, file limits and error messages, and working with read-only imported surveys. ## What an import does An import turns a survey definition file into a new survey in Voxworks. The file you upload is kept as an **immutable snapshot**, and its content becomes a **read-only imported version** — the snapshot stays the authority on what the survey says. Imports accept **Voxworks JSON survey definitions**. Support for Qualtrics, Forsta Surveys and Voxco export files is planned. Importing needs the `surveys.create` permission. *** ## Import from platform On the surveys list, open **New survey** and choose **Import from platform**. The wizard reads: *"The import runs server-side — you can leave this page and track it in Jobs."* It has three steps. ### 1. Choose a source Pick a platform card. Each is badged **File upload only**: surveys are imported from a definition file. In the next step, upload a Voxworks JSON definition. ### 2. Provide the definition *"The file is stored as an immutable snapshot and normalised into a read-only imported version. Re-importing the same survey later creates a new version rather than editing this one."* Choose the **Definition file** and click **Start import**. Only `.json` files are accepted. ### 3. Import The import runs through four stages: | Stage | Shows | | --------------------------- | --------------------------------------------------------------------------------------- | | **Save source snapshot** | The file name and its fingerprint. | | **Normalize questionnaire** | *(n) sections · (n) questions · (n) options* | | **Validate support** | *(n) supported · (n) transformed · (n) read-only · (n) unsupported*, plus any blockers. | | **Finalize version** | *Imported version created — read-only* | If the identical file was imported before, it is recognised as **Already imported** and the existing survey is reused. Finish with **Open the imported survey**, **View jobs** or **Import another**. *** ## Upload new version To update an imported survey, open it and click **Upload new version** in the workspace header (it needs `surveys.edit`). The dialog has three steps — **Choose file**, **Review source**, **Import**: * The drop zone reads **Choose a survey definition** — *"Voxworks canonical JSON v1, up to 5 MB. PDF and Word documents are intentionally rejected because they are not structured survey definitions."* * **Download canonical JSON example** saves `voxworks-survey-example.json`, a small working definition to start from. * **Review source** shows the **Provider**, **Parser format**, **Acquisition**, **Content type** and **SHA-256 fingerprint**, with the note *"The original file is retained as an immutable source snapshot. Imported content stays read-only; create a Voxworks copy when you need to edit it."* * Click **Import new version**. The upload becomes the survey's next version, also read-only. The confirmation is *Imported version with (n) questions*; an identical file gives *This exact upload already exists — opening it now*. *** ## The JSON format A Voxworks survey definition is a JSON object: ```json theme={null} { "schemaVersion": 1, "provider": "voxworks", "sourceFormat": "voxworks_canonical_json_v1", "name": "Customer follow-up", "description": "A minimal structured survey definition.", "defaultLanguage": "en-AU", "targetChannel": "voice", "blocks": [ { "key": "experience", "title": "Experience", "questions": [ { "key": "satisfaction", "type": "single_choice", "prompt": "Were you satisfied with your experience?", "required": true, "options": [ { "key": "yes", "text": "Yes" }, { "key": "no", "text": "No" } ] }, { "key": "comments", "type": "long_text", "prompt": "What could we do better?", "required": false } ] } ] } ``` | Field | Required | What it holds | | -------------------------- | ------------------------------ | ------------------------------------------------------------------------ | | `name` | Yes | The survey's name. | | `schemaVersion` | No | `1` or `2`. | | `provider`, `sourceFormat` | No | Where the definition came from. | | `description` | No | The survey's description. | | `defaultLanguage` | No | The language code. | | `targetChannel` | No | `voice`. | | `blocks` | One of `blocks` or `questions` | Sections, each with a `key`, `title` and `questions`. | | `questions` | One of `blocks` or `questions` | Questions without sections. | | `rules` | No | Routing rules — up to 5,000. | | `variables` | No | Survey variables — up to 500. | | `outcomes` | No | Outcome codes — up to 500. | | `voice` | No | Fixed-section settings: agent, FAQs, behaviours, gatekeeper and closing. | ### Question types Each question's `type` can be a Voxworks type or a common alias: | `type` in the file | Imported as | | ----------------------------------------------------------------- | ------------- | | `display`, `info`, `instruction` | Display | | `single_choice`, `radio`, `single`, `single_select`, `select_one` | Single choice | | `rating`, `scale` | Rating | | `number`, `numeric`, `integer` | Number | | `long_text`, `textarea` | Long text | | `first_name`, `firstname`, `given_name` | First name | | `phone`, `phone_number` | Phone number | Other types — multiple choice, short text, email, date, matrix, rank order, constant sum, file upload and so on — are kept so you can read them, but voice cannot run them. The question inspector shows them with *"Not supported for voice. The question can be read and deleted; its type cannot be changed here."* Matrix, rank order and similar grid types are also flagged in [Readiness](/surveys/readiness) as *preserved for inspection only*. In a Voxworks copy, delete these questions or rebuild them as a voice type. ### Limits and errors | Limit | Value | | --------- | ------ | | File size | 5 MB | | Sections | 500 | | Questions | 10,000 | | Options | 50,000 | | Message | Cause | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | *"The uploaded file is empty."* | The file has no content. | | *"The uploaded file exceeds the 5 MB limit."* | The file is too large. | | *"Only structured JSON survey definitions are supported."* | The file is not a `.json` file. | | *"The uploaded file is not valid JSON."* | The JSON cannot be read. | | *"The survey definition is invalid: (first issue)"* | A field is missing or wrong — for example *"The file must contain at least one block or question."* | | *"The survey exceeds the supported question or option limit."* | Too many questions or options. | | *"The definition must include a survey name."* | `name` is missing (**Upload new version** dialog). | | *"Choose a structured JSON survey definition."* | The file is not a `.json` file (**Upload new version** dialog). | | *"The file exceeds the 5 MB limit."* | The file is too large (**Upload new version** dialog). | *** ## Working with an imported survey An imported survey is **read-only for good**. Its workspace shows a **🔒 Imported** badge and the banner *"Imported versions are read-only."* — *"The uploaded snapshot remains authoritative. Create a Voxworks copy to change questions or logic."* A provenance strip shows the source's id, *snapshot (date)* and a **Source details** link to the [Settings tab](/surveys/settings-tab). To edit it: 1. Click **Create Voxworks copy** in the header. 2. The copy is a new, fully editable survey made from the import's latest version — see [Versions and drafts](/surveys/versions#copies). 3. Add what an import does not carry, such as a **Voice** in the [Agent](/surveys/agent) section, then validate, test and publish it. Import jobs are listed on the [Jobs](/surveys/jobs) page. A failed import never leaves a half-built version behind.