Import & export
Bring existing surveys into Flashpoint.AI from Word documents, and export data, instruments, and platform files in the format your downstream tools need.
Import
DOCX upload
Upload a .docx questionnaire — a paper survey, legacy Word file, vendor handoff — and Flashpoint.AI programs it into a live survey automatically. The AI pipeline reads the document structure, identifies questions, applies logic and routing, validates the result, and lands a draft you can review.
Endpoint
POST /api/v1/imports/docx
Content-Type: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | .docx file, 10 MB max |
output_format | string | No | Target platform writer. Default: decipher |
conversation_id | UUID | No | Chat conversation to receive progress events |
notify_email | string | No | Email address for completion notification |
Example
curl -X POST https://surveys.flashpoint.ai/api/v1/imports/docx \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID" \
-F "file=@survey-spec.docx" \
-F "output_format=decipher" \
-F "notify_email=researcher@company.com"
Response (immediate — the actual import runs asynchronously)
{
"job_id": "a1b2c3d4-...",
"artifact_id": "a1b2c3d4-...",
"state": "pending",
"output_format": "decipher",
"conversation_id": "e5f6a7b8-...",
"filename": "survey-spec.docx",
"title": "survey-spec.docx"
}
Polling for status
GET /api/v1/imports/{job_id}
curl https://surveys.flashpoint.ai/api/v1/imports/a1b2c3d4-... \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
{
"job_id": "a1b2c3d4-...",
"state": "completed",
"output_format": "decipher",
"survey_id": "f8e7d6c5-...",
"error": null,
"started_at": "2026-05-26T10:01:00Z",
"completed_at": "2026-05-26T10:07:42Z"
}
Job states
| State | Meaning |
|---|---|
pending | Queued, waiting for a worker |
processing | Pipeline running (reading, understanding, programming, validating) |
completed | Survey created successfully — survey_id is populated |
failed | Pipeline error — error contains details |
What the pipeline does
| Stage | Description |
|---|---|
| Reading | Renders the .docx to a structured representation. Tables, formatting, and section markers are preserved. |
| Understanding | Identifies sections — screener, demographics, body, terminations — and estimates question counts. |
| Programming | One focused AI call per question. Determines type, options, logic targets, and any quotas. |
| Validating | Structural checks: option sets have at least two options, skip targets resolve, types match schemas. |
| Auto-fixing | Known-fixable issues (empty options, orphan skip targets, missing terminations) are rewritten and re-validated. |
Processing typically takes 5-10 minutes for a real-world questionnaire.
Via the agent
Upload a .docx in the chat interface, or tell the agent:
"Upload this survey spec and program it"
The agent shows a progress card that ticks through each stage live.
Export formats
Flashpoint.AI supports exporting survey data and instruments in multiple formats. Some exports are synchronous (the response body is the file); others are asynchronous (you get a job ID and poll or wait for an event).
Format reference
| Format | Endpoint | Method | Mode | Description |
|---|---|---|---|---|
| CSV | /api/v1/surveys/{id}/exports/csv | GET | Sync | SPSS-compatible wide format, one column per option |
| XLSX | /api/v1/surveys/{id}/exports/xlsx | GET | Sync | Wide format with a Questions codebook sheet |
/api/v1/surveys/{id}/exports/pdf | GET | Sync | Survey instrument as a PDF document | |
| DOCX | /api/v1/surveys/{id}/exports/docx | GET | Sync | Survey instrument as a Word document |
| Confirmit XML | /api/v1/surveys/{id}/exports/confirmit | GET | Sync | Confirmit-compatible XML inside a ZIP archive |
| Qualtrics QSF | /api/v1/surveys/{id}/exports/qualtrics | POST | Async | Qualtrics survey file |
| Forsta XML | /api/v1/surveys/{id}/exports/forsta | POST | Async | Forsta-compatible XML |
CSV export
SPSS-compatible wide-format CSV with a two-row header (question label group + column IDs). One column per option, grid row, MaxDiff set, etc.
curl -o responses.csv \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/csv?with_labels=false" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
| Parameter | Type | Default | Description |
|---|---|---|---|
version | integer | current | Specific survey version number |
with_labels | boolean | false | false: cells contain option IDs (SPSS codes). true: cells contain display text. |
XLSX export
Same wide-format layout as CSV, plus a Questions codebook sheet documenting every question and its options.
curl -o responses.xlsx \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/xlsx?with_labels=true" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
Parameters are identical to CSV.
PDF export
Exports the survey instrument (questions, options, logic) as a formatted PDF. This is the survey design, not response data — useful for stakeholder review, IRB submissions, or archival.
curl -o instrument.pdf \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/pdf" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
DOCX export
Survey instrument as a Word document. Stakeholders can review, mark up, and share offline.
curl -o instrument.docx \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/docx" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
Confirmit XML export
Generates Confirmit-compatible XML with team-specific customizations (CATI templates, form logic, USW splits) applied automatically. Returned as a ZIP archive.
curl -o confirmit.zip \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/confirmit" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
Async exports (Qualtrics, Forsta)
Qualtrics QSF and Forsta XML exports run asynchronously. You receive a job ID and poll for completion.
curl -X POST \
"https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/qualtrics" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID" \
-H "Content-Type: application/json"
{
"export_id": "b2c3d4e5-...",
"format": "qualtrics_qsf",
"status": "pending",
"message": "Qualtrics QSF export requested."
}
The generic async export endpoint also supports all formats:
POST /api/v1/surveys/{id}/exports
{
"format": "csv",
"version": null,
"filters": { "status": "COMPLETE", "date_from": "2026-01-01" },
"options": { "include_open_ended": true }
}
Pre-check
Before triggering an export, validate that it will succeed. The pre-check endpoint returns blockers (hard stops) and warnings (informational).
GET /api/v1/surveys/{id}/exports/precheck?format=csv
curl "https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/exports/precheck?format=csv" \
-H "X-Service-Token: $TOKEN" \
-H "X-Team-ID: $TEAM_ID" \
-H "X-User-ID: $USER_ID"
{
"ok": true,
"format": "csv",
"total_responses": 847,
"blockers": [],
"warnings": []
}
Possible blockers:
"Survey has no responses to export.""Unsupported format 'xyz'."
Possible warnings:
"Large export (150,000 responses) — may take several minutes to build.""Low completion rate (8%) — many responses are incomplete."
Document generation
The agent can compose free-form documents from platform data — analysis summaries, methodology writeups, stakeholder memos. These are distinct from the fixed-template instrument exports above.
Formats
| Tool | Output | Use case |
|---|---|---|
generate_docx | Word document (.docx) | Narrative reports, methodology docs, memos. Sections with headings, paragraphs, and tables. |
generate_xlsx | Excel workbook (.xlsx) | Multi-sheet tabular data. Numeric types preserved for formulas. |
generate_csv | CSV file (.csv) | Simple flat tables — response dumps, recipient lists. |
generate_pdf | PDF document (.pdf) | Polished final reports. Same input shape as generate_docx. |
All generated documents are uploaded to S3 and returned as presigned download URLs valid for 1 hour. The chat displays a preview card with inline content.
Agent examples
"Generate a Word report summarizing the survey results with charts and takeaways"
The agent fetches the analytics data, composes a structured document with sections, tables, and narrative, and produces a downloadable .docx.
"Export the response data as an Excel file with separate sheets for each question"
The agent calls generate_xlsx with one sheet per question, headers as option labels, and rows as response counts.
"Create a PDF summary I can send to the client"
The agent composes a polished PDF with title, executive summary, key findings, and detailed breakdowns.
How it differs from export endpoints
| Export endpoints | Document generation | |
|---|---|---|
| Content | Fixed template — survey instrument or raw response data | Free-form — agent composes narrative, tables, analysis |
| Access | Direct HTTP endpoints | Agent tool calls (via chat or API) |
| Customization | Query parameters (with_labels, version) | Natural language ("include only Q1-Q5", "add an executive summary") |
Sending generated documents by email
After generating a document, the agent can email it to stakeholders using the send_platform_email tool. This requires at least one attachment and supports up to 10 recipients and 5 attachments per send. The send requires explicit approval before executing.
"Generate the results summary as a PDF and email it to team@company.com"