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

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

Error Scenarios

Error Codes Reference

Tags: WalkSchedule

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 scheduled. Returns response from schedule processing.

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

401 — Missing or invalid X-reflexis-csrf-token-X session token.

Content type: application/json

500 — Unexpected server-side error.

Content type: application/json

Request body

Required: Yes

multipart/form-data

Schema

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

{
  "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."
    },
    "category_id": {
      "type": "string",
      "description": "**Required.** Category identifier."
    },
    "start_date": {
      "type": "string",
      "description": "**Required.** Walk start date. **Format:** `YYYY-MM-DD`.\n",
      "example": "2026-04-13"
    },
    "end_date": {
      "type": "string",
      "description": "**Required.** Walk end date. **Format:** `YYYY-MM-DD`.\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. Length-limited.",
      "example": "Regional Compliance Q2"
    },
    "walk_description": {
      "type": "string",
      "description": "**Required.** Walk description. Length-limited.",
      "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. Returns response from schedule processing.

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).

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

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.

{
  "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": "E110",
    "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": "E110",
  "response": "model_id is mandatory"
}

401 — Missing or invalid X-reflexis-csrf-token-X session token.

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.

{
  "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": "E110",
    "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"
        }
      ]
    }
  }
}

500 — Unexpected server-side 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.

{
  "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": "E110",
    "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": "E500",
  "response": "Unexpected server error."
}