Submit a session action

Submit user input for a step that is waiting for a mid-workflow action

Some steps expect your backend to collect input from the end-user and submit it through the API rather than through the Player — for example, submitting an OTP code. Use this endpoint to submit that input for the step currently active on a session. Discover which actions are available, and their exact payload shape, via Get current step.

Endpoint

POST /api/v1/{environment}/sessions/{sessionId}/actions

Path parameters

Parameter	Type	Required	Description
sessionId	string	Yes	The unique identifier of the session
environment	string	Yes	Environment name

Request

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json
X-Ticket-Id	string	Yes	Value of ticketId from the most recent GET /step response

Ticket ID guards against replay

X-Ticket-Id must match the ticketId currently stored for the session. It is consumed on a successful submission — always fetch a fresh ticketId via GET /step before each action. A stale or mismatched value returns 409 Conflict.

Request body

The body is a JSON object with a type field identifying the action, plus any fields required by that action's schema (as returned by GET /step). Never hardcode the accepted fields — validate against the schema from the latest /step response.

Field	Type	Required	Description
type	string	Yes	Action identifier, matching one of the actions[].type values returned by GET /step

Example — validateOtp (PHONE_VERIFY:v1)

{ "type": "validateOtp", "otp": "123456" }

Field	Type	Validation	Description
otp	string	6 digits ([0-9]{6})	The code sent by SMS

curl --request POST https://localhost:3000/api/v1/live/sessions/0197c55f-5af6-7e3d-af9b-f2359b104be8/actions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Ticket-Id: fa85a81e-c935-4366-b14d-dc82fe2284ef" \
-d '{ "type": "validateOtp", "otp": "123456" }'

Example — resendOtp (PHONE_VERIFY:v1)

{ "type": "resendOtp" }

Requests a new code for the current step. Only accepted while the step still allows generating new codes — see Phone number verification (v1) for the full state table.

Response

202 Accepted — the action was accepted and forwarded to the workflow. The response has no body. Poll GET /step to observe the resulting state.

Error responses

Status	Condition
400	Missing X-Ticket-Id header, or request body failed schema validation (e.g. otp is not 6 digits)
401	Missing or invalid Bearer token
403	Environment mismatch — the token's authorised environment does not match the {environment} path parameter
404	Session not found, or the session belongs to a different organisation than the token
409	X-Ticket-Id does not match the current step state, or the action is not valid for the step's current state

Notes

• Only steps documented as accepting mid-workflow actions expose this behaviour — currently Phone number verification (v1). Submitting an action while no step is waiting for one returns 409 Conflict.
• Always fetch the current ticketId and actions from GET /step immediately before submitting — do not cache or reuse a ticketId across polls.