Schedule a walk for distribution to stores (multipart/form-data)

POST /walk/v1/walks/schedule

Operation id: createScheduledWalk

Description

Schedules a walk and distributes it to the specified stores. The request must be sent as multipart/form-data.

The eleven required fields must be present. Missing any required field returns HTTP 400 with a validation error message listing missing fields.

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> } (no message).

Schedule processing returns service-specific keys (often includes walk_list or status fields); all normalized to snake_case.

{
  "response": {
    "walk_list": []
  },
  "status": "OK"
}
FieldDescription
responseJSON object from schedule processing

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 field is checked individually; first failure returns HTTP 400 with a per-parameter error code (see Error Codes Reference below)
Walk name exceeds 100 characters400Walk name length should not exceed 100 characters
Walk description exceeds 400 characters400Walk description length should not exceed 400 characters
Invalid date format (e.g. 2026-36-36)400start_date must be a valid date in yyyy-MM-dd format
end_date before start_date400end_date must not be before start_date
Non-existing model_id400model_id does not exist or is not active
Non-existing category_id400category_id does not exist
Invalid store assignment (not in distribution)403Invalid Instance Access
Service-layer scheduling error400Error while scheduling the walk
Internal server error500Unexpected server error.

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
E108400walk_name is mandatory
E109400walk_description is mandatory
E112400model_id is mandatory
E113400category_id is mandatory
E114400start_date is mandatory
E115400end_date is mandatory
E116400start_time is mandatory
E120400created_by is mandatory
E121400creator_unit is mandatory
E122400cluster_child_id is mandatory
E123400assign_store_list is mandatory
E210400Invalid date format (must be yyyy-MM-dd)
E211400end_date must not be before start_date
E212400model_id does not exist or is not active
E213400category_id does not exist
E301400Walk name exceeds max length (100 chars)
E302400Walk description exceeds max length (400 chars)
E202403Invalid Instance Access (store not in distribution)
E304400Error while scheduling the walk (service-layer validation)
E500500Unhandled server error

Tags: WalkSchedule

Security

  • 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 scheduled successfully.

Content type: application/json

400 — Invalid or missing required request parameter. Possible error codes:

  • E108–E123: mandatory field missing
  • E210: invalid date format
  • E211: end_date before start_date
  • E212: model_id does not exist
  • E213: category_id does not exist
  • E301: walk_name exceeds 100 characters
  • E302: walk_description exceeds 400 characters
  • E304: service-layer scheduling error

Content type: application/json

403 — Store assignment not in distribution list (Invalid Instance Access).

Content type: application/json

Request body

Required: Yes

multipart/form-data

Schema

Walk schedule form data. All required properties must be present.

PropertyTypeRequiredDescription
model_idstringYesRequired. Walk template/model identifier. Must reference an existing active walk template. Returns HTTP 400 (E212) if not found.
category_idstringYesRequired. Category identifier. Must reference an existing walk category. Returns HTTP 400 (E213) if not found.
start_datestring (date)YesRequired. Walk start date. Format: YYYY-MM-DD (strict — invalid calendar dates like 2026-36-36 are rejected). Must not be after end_date.
end_datestring (date)YesRequired. Walk end date. Format: YYYY-MM-DD (strict — invalid calendar dates are rejected). Must not be before start_date.
start_timestringYesRequired. Walk start time. Format: h:mm AM/PM.
walk_namestringYesRequired. Display name for the scheduled walk. Maximum 100 characters. Returns HTTP 400 (E301) if exceeded.
walk_descriptionstringYesRequired. Walk description. Maximum 400 characters. Returns HTTP 400 (E302) if exceeded.
created_bystringYesRequired. Creator user identifier (login ID).
creator_unitstringYesRequired. Creator's unit/store identifier.
cluster_child_idstringYesRequired. Cluster child identifier. Use "-1" when not applicable to a specific cluster child.
assign_store_liststringYesRequired. Comma-separated list of store/unit IDs to assign the scheduled walk to. Obtained from GET /walk/v1/walks/stores.
image_keystringNoOptional image key for the walk's cover image.
announced_visitstringNoOptional announced visit flag (Y/N). Indicates whether the visit is announced to the assigned stores.
visit_profile_mapstringNoOptional visit profile mapping. JSON-encoded object mapping visit profiles. Pass "{}" when no profile mapping is required.
walk_participantsstringNoOptional walk participants list. Comma-separated user identifiers.
time_zone_longstringNoOptional IANA time zone ID for the scheduled walk.
reference_keystringNoOptional reference key for external system correlation.
time_zone_off_setstringNoOptional time zone offset in minutes from UTC. Negative for west of UTC.
max_org_lvlstringNoOptional maximum org level for distribution scope calculation.
schedule_categorystringNoOptional schedule category code: - S — Standard scheduled walk
offline_flagstringNoOptional offline distribution flag: - Y — distribute as offline-enabled - N — standard online distribution (default)
future_flagstringNoOptional future walk flag: - Y — create as a future scheduled walk - N — create as immediately active
form_trace_idstringNoOptional form trace identifier; used for rescheduling an existing walk.
{
  "type": "object",
  "description": "Walk schedule form data. All required properties must be present.",
  "required": [
    "model_id",
    "category_id",
    "walk_name",
    "walk_description",
    "start_date",
    "start_time",
    "end_date",
    "created_by",
    "creator_unit",
    "cluster_child_id",
    "assign_store_list"
  ],
  "properties": {
    "model_id": {
      "type": "string",
      "description": "**Required.** Walk template/model identifier. Must reference an existing\nactive walk template. Returns HTTP 400 (E212) if not found.\n"
    },
    "category_id": {
      "type": "string",
      "description": "**Required.** Category identifier. Must reference an existing walk category.\nReturns HTTP 400 (E213) if not found.\n"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "**Required.** Walk start date. **Format:** `YYYY-MM-DD` (strict — invalid\ncalendar dates like `2026-36-36` are rejected). Must not be after `end_date`.\n",
      "example": "2026-04-13"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "**Required.** Walk end date. **Format:** `YYYY-MM-DD` (strict — invalid\ncalendar dates are rejected). Must not be before `start_date`.\n",
      "example": "2026-04-13"
    },
    "start_time": {
      "type": "string",
      "description": "**Required.** Walk start time. **Format:** `h:mm AM/PM`.\n",
      "example": "12:00 AM"
    },
    "walk_name": {
      "type": "string",
      "description": "**Required.** Display name for the scheduled walk. Maximum 100 characters.\nReturns HTTP 400 (E301) if exceeded.\n",
      "example": "Regional Compliance Q2"
    },
    "walk_description": {
      "type": "string",
      "description": "**Required.** Walk description. Maximum 400 characters.\nReturns HTTP 400 (E302) if exceeded.\n",
      "example": "Q2 regional compliance inspection"
    },
    "created_by": {
      "type": "string",
      "description": "**Required.** Creator user identifier (login ID).",
      "example": "SYSADMIN"
    },
    "creator_unit": {
      "type": "string",
      "description": "**Required.** Creator's unit/store identifier.",
      "example": "1001"
    },
    "cluster_child_id": {
      "type": "string",
      "description": "**Required.** Cluster child identifier. Use `\"-1\"` when not applicable to\na specific cluster child.\n",
      "example": "-1"
    },
    "assign_store_list": {
      "type": "string",
      "description": "**Required.** Comma-separated list of store/unit IDs to assign the scheduled\nwalk to. Obtained from `GET /walk/v1/walks/stores`.\n",
      "example": "Store1,Store2"
    },
    "image_key": {
      "type": "string",
      "description": "Optional image key for the walk's cover image."
    },
    "announced_visit": {
      "type": "string",
      "description": "Optional announced visit flag (`Y`/`N`). Indicates whether the visit is\nannounced to the assigned stores.\n",
      "enum": [
        "Y",
        "N"
      ]
    },
    "visit_profile_map": {
      "type": "string",
      "description": "Optional visit profile mapping. JSON-encoded object mapping visit profiles.\nPass `\"{}\"` when no profile mapping is required.\n",
      "example": "{}"
    },
    "walk_participants": {
      "type": "string",
      "description": "Optional walk participants list. Comma-separated user identifiers."
    },
    "time_zone_long": {
      "type": "string",
      "description": "Optional IANA time zone ID for the scheduled walk.\n",
      "example": "US/Central"
    },
    "reference_key": {
      "type": "string",
      "description": "Optional reference key for external system correlation."
    },
    "time_zone_off_set": {
      "type": "string",
      "description": "Optional time zone offset in minutes from UTC. Negative for west of UTC.\n",
      "example": "-330"
    },
    "max_org_lvl": {
      "type": "string",
      "description": "Optional maximum org level for distribution scope calculation."
    },
    "schedule_category": {
      "type": "string",
      "description": "Optional schedule category code:\n- `S` — Standard scheduled walk\n",
      "example": "S"
    },
    "offline_flag": {
      "type": "string",
      "description": "Optional offline distribution flag:\n- `Y` — distribute as offline-enabled\n- `N` — standard online distribution (default)\n",
      "enum": [
        "Y",
        "N"
      ],
      "example": "N"
    },
    "future_flag": {
      "type": "string",
      "description": "Optional future walk flag:\n- `Y` — create as a future scheduled walk\n- `N` — create as immediately active\n",
      "enum": [
        "Y",
        "N"
      ],
      "example": "Y"
    },
    "form_trace_id": {
      "type": "string",
      "description": "Optional form trace identifier; used for rescheduling an existing walk."
    }
  }
}

Response models

200 — Walk scheduled successfully.

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"
        }
      }
    }
  }
}

Example:

{
  "status": "OK",
  "response": {
    "walk_list": []
  }
}

400 — Invalid or missing required request parameter. Possible error codes:

  • E108–E123: mandatory field missing
  • E210: invalid date format
  • E211: end_date before start_date
  • E212: model_id does not exist
  • E213: category_id does not exist
  • E301: walk_name exceeds 100 characters
  • E302: walk_description exceeds 400 characters
  • E304: service-layer scheduling error

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"
        }
      ]
    }
  }
}

403 — Store assignment not in distribution list (Invalid Instance Access).

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": "E202",
  "response": "Invalid Instance Access"
}