Update a Kiosk Execution

Purpose

To execute a transition in an ongoing Kiosk execution by submitting the required transition and runtime data, and proceed to the next step of the Kiosk in your Zoho CRM.

Prerequisite:
The Kiosk must be in the published status and have an active execution to update its execution state. To obtain the execution_ID, execute the Kiosk using the Execute a Kiosk API. If an execution is already in progress, invoke the Get Executions of a Kiosk API to retrieve the execution_ID.

Note
Availability: Standard, Professional, Enterprise, and Ultimate editions.

Endpoints

PUT /settings/kiosks/{kiosk_ID}/executions/{execution_ID}/actions/execute

{kiosk_ID} : The unique ID of the published Kiosk whose execution you want to update.
{execution_ID} : The unique ID of the execution you want to update.

Request Details

Request URL

{api-domain}/crm/{version}/settings/kiosks/{kiosk_ID}/executions/{execution_ID}/actions/execute

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.kiosks.ALL
(or)
ZohoCRM.settings.kiosks.UPDATE

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/kiosks/2296900000011327078/executions/2296900000011330230/actions/execute"
-X PUT
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.xxxxxxxxxxxxx"

Input JSON

The request body must be a JSON object with a kiosk_executions array. Each object in the array should have the following:

transitionJSON object, mandatory
Specify the transition information for the next execution.
- idstring, mandatory
  Specify the ID of the next transition.
- namestring, optional
  Specify the name of the next transition.
dataJSON object, mandatory
Specify the runtime values for the fields and data elements required to execute the selected transition. The keys in this object correspond to the API names of the configured Kiosk fields, merge fields, and Get Records elements. The structure of this object varies depending on the Kiosk configuration.

Note
Invoke the Get specific execution of a Kiosk endpoint to retrieve the available transition and execution details required in the data object.

Sample Input

Copied{
    "kiosk_executions": [
        {
            "transition": {
                "id": "5039614000001219596",
                "name": "Done"
            },
            "data": {
                "CurrentRecord": {
                    "id": "5039614000001049001"
                },
                "elements": [
                    {
                        "type": "text",
                        "value": "Text Element"
                    }
                ]
            }
        }
    ]
}

Response JSON

The response body is a JSON object containing a kiosk_executions array. Each object in the array contains the following fields:

code string
The status code of the execution operation.
detailsJSON object
Contains detailed information about the Kiosk execution.
- next_executable_stateJSON object
  Contains information about the next executable state in the Kiosk flow. Returns null when the Kiosk execution has reached its end and there are no further states to execute.
  - namestring
    The display name of the next executable state.
  - id string
    The unique identifier of the next executable state.
- executed_dependent_statesJSON array
  Contains the states that were executed automatically after the specified transition and do not require user interaction.
  For example: If a transition from a Screen automatically executes a Decision state and an Add Tags action before reaching the next Screen, the Decision and Add Tags states are returned in executed_dependent_states, while the next Screen is returned as the next_executable_state.
  - namestring
    The display name of the executed dependent state.
  - idstring
    The unique identifier of the executed dependent state.
  - typestring
    The type of the executed dependent state.
    Possible values:
    - create_record
    - convert
    - open_record
    - open_link
    - add_meeting
    - schedule_call
    - assign_owner
    - add_tags
    - remove_tags
    - field_updates
    - tasks
    - email_notifications
    - webhooks
    - decision
  - transitionJSON object
    Contains information about the transition taken from this dependent state.
    - namestring
      The display name of the transition taken.
    - idstring
      The unique identifier of the transition taken.
- idstring
  The unique identifier of the execution record.
messagestring
A descriptive message about the execution operation result.
statusstring
The status of the execution operation.

Possible Errors

INVALID_DATA HTTP 400
- No such Kiosk exists.
  Resolution: Specify a valid Kiosk ID in the request URL. You can get the list of valid Kiosk IDs using the Get Kiosk API.
- Invalid Kiosk transition given for execution.
  Resolution: Specify a valid transition ID in the request body. It should belong to the current executable state. Use the Get Kiosk Executions API for ID.
- Invalid Kiosk execution ID
  Resolution: Specify a valid execution ID in the request body. Use the Get Kiosk Executions API for ID.
OAUTH_SCOPE_MISMATCH HTTP 401
Invalid oauth scope to access this URL.
Resolution: Create a new token with the required scopes. Refer to the scope section.
AUTHENTICATION_FAILURE HTTP 401
Authentication Failed.
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERN HTTP 404
Please check if the URL trying to access is a correct one.
Resolution: Specify valid URL. Check the Endpoints section.
MANDATORY_NOT_FOUND HTTP 404
- Required field not found.
  Resolution: Specify kiosk_executions array in request body. Check the Input JSON section.
- Executable data information missing.
  Resolution: Specify data array in request body. Check the Input JSON section.

Sample Response

Copied{
    "kiosk_executions": [
        {
            "code": "SUCCESS",
            "details": {
                "next_executable_state": null,
                "executed_dependent_states": [
                    {
                        "name": "Tag",
                        "id": "5039614000000957754",
                        "type": "add_tags",
                        "transition": {
                            "name": "Tag",
                            "id": "5039614000000957762"
                        }
                    }
                ],
                "id": "5039614000000947101"
            },
            "message": "Kiosk transition executed successfully",
            "status": "success"
        }
    ]
}