Submit questionnaire answers for a walk instance (multipart/form-data)
POST /walk/v1/walks/submit
Operation id: submitWalkQuestionnaire
Description
Submits the questionnaire answers for an in-progress walk instance. The request must be sent as multipart/form-data.
All four required fields must be present. Missing any required field returns HTTP 400.
Authentication: X-reflexis-csrf-token-X required.
Request Headers
| Header | Required | Description |
|---|---|---|
X-reflexis-csrf-token-X | Yes | Session authentication token |
Content-Type | Yes | Must be multipart/form-data |
Response Structure
Success envelope: { "status": "OK", "response": <object> } from questionnaire submission (no message). Inner fields vary (completion status, scoring, etc.) and are snake_case in JSON.
{
"response": { },
"status": "OK"
}
| Field | Description |
|---|---|
response | Normalized submission result from questionnaire upload processing |
Answers Format
The answers field must be a stringified JSON array of answer objects in either the canonical shape (qnId + nested answer) or the flat shape (question_id
- top-level
response). The server normalises both to the canonical shape before validation.
[
{
"qnId": 1,
"answer": {
"response": [{ "optionId": 1, "value": "Y", "key": "Yes" }],
"comment": ""
},
"questionType": "Y"
}
]
Attachment Upload
File bytes are never embedded in the answers JSON. Each file is a separate multipart/form-data part. The response[].value token in answers must exactly match the multipart part name for that file.
Naming convention
| Use case | Multipart part name | Matching response[].value |
|---|---|---|
Supplementary attachment on any question with attachAllowed=Y (inline type:"F" entry) | Q<qid>_ATTACH_<index> | Same token, e.g. Q1_ATTACH_1 |
Dedicated file question (questionType=F) | Q<qid>_FILE_<index> | Same token, e.g. Q4_FILE_1 |
<qid>— integer question id (matchesqnIdinanswers).<index>— 1-based attachment index per question (1,2,3, …).- For multiple files on one question, increment
<index>:Q1_ATTACH_1,Q1_ATTACH_2, …
Server-side normalisation (clients send only the public names above)
After validation succeeds the server translates public tokens to the legacy persistence keys used by the questionnaire engine (RESPONSE_ATTACH_<qid>_<index> multipart, ATTACH_<qid>_<index> in stored answers). Clients must not send RESPONSE_* or bare ATTACH_* part names unless integrating with a legacy endpoint directly.
Single-file example (Yes/No + mandatory attachment)
curl -X POST "{base}/walk/v1/walks/submit" \
-H "X-reflexis-csrf-token-X: <token>" \
-F "model_id=FORM_1" \
-F "category_id=cat1" \
-F "form_trace_id=1785317288540" \
-F 'answers=[{"qnId":1,"answer":{"response":[{"key":"Yes","value":"Y","optionId":1},{"key":"photo.jpg","value":"Q1_ATTACH_1","type":"F","fileSize":567429}],"comment":""},"questionType":"Y"}]' \
-F "Q1_ATTACH_1=@photo.jpg"
Multi-file example (two attachments on question 1)
-F 'answers=[{"qnId":1,"answer":{"response":[{"key":"a.jpg","value":"Q1_ATTACH_1","type":"F"},{"key":"b.jpg","value":"Q1_ATTACH_2","type":"F"}]}}]' \
-F "Q1_ATTACH_1=@a.jpg" \
-F "Q1_ATTACH_2=@b.jpg"
Validation rules
- When
attachMandatory=Y, at least oneQ<qid>_ATTACH_*part must be present. - Each inline
type:"F"entry inanswersmust reference an uploaded part (same name). - File count must not exceed the template
attachCountlimit. - Allowed extensions and max size are enforced per question configuration.
Error Scenarios
| Scenario | HTTP Status | Message |
|---|---|---|
Missing X-reflexis-csrf-token-X header | 400 | X-reflexis-csrf-token-X header is mandatory |
| Invalid or expired token | 401 | Invalid or expired token |
| Missing required field | 400 | <field_name> is mandatory — each mandatory param is checked individually; first failure returns HTTP 400 with a per-parameter error code (see Error Codes Reference below) |
| Questionnaire validation failed | 200 | HTTP 200 status: "ER", error is a JSON array of localized validation messages (questionnaire validation) |
| Attached file blocked by kernel security filter (unsafe/unsupported content) | 400 | Invalid file. Please upload a supported file type. — errorCode: E600 |
| Request rejected by kernel security filter (generic) | 400 | Request could not be processed. Please try again. — errorCode: E601 |
| Internal server error | 500 | Error while processing request. Here is the error : <error details> |
Error Codes Reference
| Code | HTTP | Description |
|---|---|---|
E112 | 400 | X-reflexis-csrf-token-X header is mandatory |
E101 | 400 | Domain id is mandatory (session payload) |
E202 | 401 | User session is invalid (MyWork) |
E204 | 401 | Invalid or expired token |
E112 | 400 | model_id is mandatory |
E113 | 400 | category_id is mandatory |
E124 | 400 | form_trace_id is mandatory |
E125 | 400 | answers is mandatory |
E600 | 400 | File blocked by the kernel security filter before validation (unsafe/unsupported content). Generic, module-independent. |
E601 | 400 | Request rejected by the kernel security filter (generic). Module-independent. |
E500 | 500 | Unhandled server error |
| — | 200 | Validation failures after mandatory checks: status: "ER", error only (no errorCode) |
Tags: WalkSubmit
Security
- ApiKeyHeader (apiKey)
- APIGEE API key header validated by VerifyAPIKey policy.
- AuthTokenHeader (apiKey)
- Session authentication token validated server-side against the user session store. Required on every request. Absence returns HTTP 400; invalid/expired token returns HTTP 401.
Responses
200 — Walk submitted. Returns response from questionnaire submission (completion metadata).
Application-level errors are returned as HTTP 200 with status: "ER".
Content type: application/json
400 — Invalid or missing required request parameter.
Content type: application/json
Request body
Required: Yes
multipart/form-data
Schema
Walk submission form data. All required fields must be present.
| Property | Type | Required | Description |
|---|---|---|---|
model_id | string | Yes | Required. Walk template/model identifier. |
category_id | string | Yes | Required. Category identifier associated with the model. |
form_trace_id | string | Yes | Required. Walk instance trace ID identifying the in-progress walk to submit. Obtained from GET /walk/v1/walks/ or the create walk response. |
answers | string | Yes | Required. Stringified JSON array of questionnaire answers. Use the canonical shape (qnId + nested answer.response[]) or the flat shape (question_id + top-level response[]). See operation description for attachment upload rules. Example (Yes/No with one attachment): json [{"qnId":1,"answer":{"response":[{"key":"Yes","value":"Y","optionId":1},{"key":"photo.jpg","value":"Q1_ATTACH_1","type":"F","fileSize":567429}],"comment":""},"questionType":"Y"}] |
Q1_ATTACH_1 | string (binary) | No | Conditional. Example supplementary attachment part for question 1, attachment index 1. Part name pattern: Q<qid>_ATTACH_<index>. The response[].value in answers must equal this part name. Repeat with incremented index for multiple files (Q1_ATTACH_2, …). |
Q4_FILE_1 | string (binary) | No | Conditional. Example file-question part for a dedicated file question (questionType=F). Part name pattern: Q<qid>_FILE_<index>. |
{
"type": "object",
"description": "Walk submission form data. All required fields must be present.",
"required": [
"model_id",
"category_id",
"form_trace_id",
"answers"
],
"properties": {
"model_id": {
"type": "string",
"description": "**Required.** Walk template/model identifier."
},
"category_id": {
"type": "string",
"description": "**Required.** Category identifier associated with the model."
},
"form_trace_id": {
"type": "string",
"description": "**Required.** Walk instance trace ID identifying the in-progress walk to submit.\nObtained from `GET /walk/v1/walks/` or the create walk response.\n"
},
"answers": {
"type": "string",
"description": "**Required.** Stringified JSON array of questionnaire answers.\n\nUse the **canonical** shape (`qnId` + nested `answer.response[]`) or the **flat**\nshape (`question_id` + top-level `response[]`). See operation description for\nattachment upload rules.\n\nExample (Yes/No with one attachment):\n```json\n[{\"qnId\":1,\"answer\":{\"response\":[{\"key\":\"Yes\",\"value\":\"Y\",\"optionId\":1},{\"key\":\"photo.jpg\",\"value\":\"Q1_ATTACH_1\",\"type\":\"F\",\"fileSize\":567429}],\"comment\":\"\"},\"questionType\":\"Y\"}]\n```\n",
"example": "[{\"qnId\":1,\"answer\":{\"response\":[{\"key\":\"Yes\",\"value\":\"Y\",\"optionId\":1}],\"comment\":\"\"}}]"
},
"Q1_ATTACH_1": {
"type": "string",
"format": "binary",
"description": "**Conditional.** Example supplementary attachment part for question `1`,\nattachment index `1`. Part name pattern: `Q<qid>_ATTACH_<index>`. The\n`response[].value` in `answers` must equal this part name. Repeat with\nincremented index for multiple files (`Q1_ATTACH_2`, …).\n"
},
"Q4_FILE_1": {
"type": "string",
"format": "binary",
"description": "**Conditional.** Example file-question part for a dedicated file question\n(`questionType=F`). Part name pattern: `Q<qid>_FILE_<index>`.\n"
}
}
}
Response models
200 — Walk submitted. Returns response from questionnaire submission (completion metadata).
Application-level errors are returned as HTTP 200 with status: "ER".
Content type: application/json
Schema
Successful response envelope for Walk APIs.
Named key (most GET endpoints): { "status": "OK", "<resource_key>": <payload> } — e.g. walk_categories, walks, scheduled_walks, walk_types, walk_questions, walk_stores, walk_details, walk_permissions, walk_users. There is no message property.
Default key (multipart POST — create / schedule / submit): { "status": "OK", "response": <object> }.
Nested objects and arrays are emitted in snake_case (internal camelCase field names are normalized in responses).
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | |
response | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_categories | array | No | |
walks | object | No | Generic JSON object — structure varies by endpoint and config type. |
scheduled_walks | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_types | array | No | |
walk_questions | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_stores | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_details | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_permissions | object | No | Generic JSON object — structure varies by endpoint and config type. |
walk_users | array | No | |
walk_history | object | No |
{
"type": "object",
"description": "Successful response envelope for Walk APIs.\n\n**Named key (most GET endpoints):** `{ \"status\": \"OK\", \"<resource_key>\": <payload> }` — e.g. `walk_categories`,\n`walks`, `scheduled_walks`, `walk_types`, `walk_questions`, `walk_stores`, `walk_details`, `walk_permissions`,\n`walk_users`. There is **no** `message` property.\n\n**Default key (multipart POST — create / schedule / submit):** `{ \"status\": \"OK\", \"response\": <object> }`.\n\nNested objects and arrays are emitted in **snake_case** (internal camelCase field names are normalized in responses).\n",
"example": {
"status": "OK",
"walks": {
"walk_list": [],
"last_fetch_time": 1710000000000
}
},
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"OK"
]
},
"response": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_categories": {
"type": "array",
"items": {
"type": "object",
"description": "A single walk category object.",
"properties": {
"domain_id": {
"type": "integer",
"description": "Domain identifier for the category."
},
"category_name": {
"type": "string",
"description": "Display name of the walk category."
},
"category_id": {
"type": "string",
"description": "Unique category identifier."
},
"category_type": {
"type": "string",
"description": "Category type code (e.g. `\"W\"` for walk)."
},
"category_desc": {
"type": "string",
"description": "Category description."
},
"creator_name": {
"type": "string",
"description": "Username of the category creator."
},
"permission": {
"type": "string",
"description": "Comma-separated permission flags (e.g. `\"1,1,1,1\"`)."
},
"created_by": {
"type": "string",
"description": "Login ID of the creator."
}
}
}
},
"walks": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"scheduled_walks": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_types": {
"type": "array",
"items": {}
},
"walk_questions": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_stores": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_details": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_permissions": {
"type": "object",
"description": "Generic JSON object — structure varies by endpoint and config type."
},
"walk_users": {
"type": "array",
"items": {}
},
"walk_history": {
"type": "object",
"properties": {
"history_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"state_key": {
"type": "integer"
},
"form_trace_id": {
"type": "integer",
"format": "int64"
},
"domain_id": {
"type": "integer"
},
"model_id": {
"type": "string"
},
"model_name": {
"type": "string"
},
"category_id": {
"type": "string"
},
"category_name": {
"type": "string"
},
"action_type": {
"type": "string"
},
"action_text": {
"type": "string"
},
"action_time": {
"type": "string"
},
"old_status": {
"type": "string"
},
"new_status": {
"type": "string"
},
"txn_category": {
"type": "string"
},
"permit_type": {
"type": "string"
},
"comments": {
"type": "string"
},
"from_user": {
"type": "string"
},
"from_profile": {
"type": "string"
},
"from_unit": {
"type": "string"
},
"from_dept": {
"type": "string"
},
"created_by": {
"type": "string"
},
"creator_name": {
"type": "string"
},
"send_to_user": {
"type": "string"
},
"send_to_profile": {
"type": "string"
},
"send_to_unit": {
"type": "string"
},
"send_to_dept": {
"type": "string"
}
}
}
},
"info_msg": {
"type": "string"
}
}
}
}
}
400 — Invalid or missing required request parameter.
Content type: application/json
Schema
Error envelope shape depends on how the error is produced:
- HTTP 200 — business or validation failure after the request is accepted:
{ "status": "ER", "error": "<string or JSON>" }(noerrorCode). - HTTP 4xx/5xx — structured API error:
{ "status": "ER", "errorCode": "<code>", "response": "<localized message>" }.
See the global Error Codes Reference in this spec for errorCode values.
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | |
errorCode | string | No | Structured error code (Walk or shared session codes; see Error Codes Reference). |
response | string | No | Human-readable message when errorCode is present (HTTP 4xx/5xx responses). |
error | oneOf | No | Payload for HTTP 200 error bodies (string, array, or object). |
{
"type": "object",
"description": "Error envelope shape depends on how the error is produced:\n\n- **HTTP 200** — business or validation failure after the request is accepted:\n `{ \"status\": \"ER\", \"error\": \"<string or JSON>\" }` (no `errorCode`).\n- **HTTP 4xx/5xx** — structured API error:\n `{ \"status\": \"ER\", \"errorCode\": \"<code>\", \"response\": \"<localized message>\" }`.\n\nSee the global **Error Codes Reference** in this spec for `errorCode` values.\n",
"example": {
"status": "ER",
"errorCode": "E112",
"response": "model_id is mandatory"
},
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Structured error code (Walk or shared session codes; see **Error Codes Reference**)."
},
"response": {
"type": "string",
"description": "Human-readable message when `errorCode` is present (HTTP 4xx/5xx responses)."
},
"error": {
"description": "Payload for HTTP 200 error bodies (string, array, or object).",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {}
},
{
"type": "object"
}
]
}
}
}
Example:
{
"status": "ER",
"errorCode": "E112",
"response": "model_id is mandatory"
}