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

HeaderRequiredDescription
X-reflexis-csrf-token-XYesSession authentication token
Content-TypeYesMust 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"
}
FieldDescription
responseNormalized 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 caseMultipart part nameMatching 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 (matches qnId in answers).
  • <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 one Q<qid>_ATTACH_* part must be present.
  • Each inline type:"F" entry in answers must reference an uploaded part (same name).
  • File count must not exceed the template attachCount limit.
  • Allowed extensions and max size are enforced per question configuration.

Error Scenarios

ScenarioHTTP StatusMessage
Missing X-reflexis-csrf-token-X header400X-reflexis-csrf-token-X header is mandatory
Invalid or expired token401Invalid or expired token
Missing required field400<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 failed200HTTP 200 status: "ER", error is a JSON array of localized validation messages (questionnaire validation)
Attached file blocked by kernel security filter (unsafe/unsupported content)400Invalid file. Please upload a supported file type. — errorCode: E600
Request rejected by kernel security filter (generic)400Request could not be processed. Please try again. — errorCode: E601
Internal server error500Error while processing request. Here is the error : <error details>

Error Codes Reference

CodeHTTPDescription
E112400X-reflexis-csrf-token-X header is mandatory
E101400Domain id is mandatory (session payload)
E202401User session is invalid (MyWork)
E204401Invalid or expired token
E112400model_id is mandatory
E113400category_id is mandatory
E124400form_trace_id is mandatory
E125400answers is mandatory
E600400File blocked by the kernel security filter before validation (unsafe/unsupported content). Generic, module-independent.
E601400Request rejected by the kernel security filter (generic). Module-independent.
E500500Unhandled server error
—200Validation 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.

PropertyTypeRequiredDescription
model_idstringYesRequired. Walk template/model identifier.
category_idstringYesRequired. Category identifier associated with the model.
form_trace_idstringYesRequired. Walk instance trace ID identifying the in-progress walk to submit. Obtained from GET /walk/v1/walks/ or the create walk response.
answersstringYesRequired. 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_1string (binary)NoConditional. 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_1string (binary)NoConditional. 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).

PropertyTypeRequiredDescription
statusstringYes
responseobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_categoriesarrayNo
walksobjectNoGeneric JSON object — structure varies by endpoint and config type.
scheduled_walksobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_typesarrayNo
walk_questionsobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_storesobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_detailsobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_permissionsobjectNoGeneric JSON object — structure varies by endpoint and config type.
walk_usersarrayNo
walk_historyobjectNo
{
  "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>" } (no errorCode).
  • 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.

PropertyTypeRequiredDescription
statusstringYes
errorCodestringNoStructured error code (Walk or shared session codes; see Error Codes Reference).
responsestringNoHuman-readable message when errorCode is present (HTTP 4xx/5xx responses).
erroroneOfNoPayload 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"
}