Execute a Kiosk

Purpose

The execute Kiosk API is used to trigger the execution of a published Kiosk in Zoho CRM.

This API returns only the first executable state of the Kiosk. To continue the execution through the remaining states, call the Update a Kiosk Execution API until the execution is complete.

Prerequisite:
Use the Get Kiosks API to obtain the kiosk_ID.

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

Endpoints

POST /settings/kiosks/{kiosk_ID}/actions/execute

{kiosk_ID} : The unique ID of the published Kiosk you want to execute

Request Details

Request URL

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Sample Request

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

Input JSON

The request body must be a JSON object containing the kiosk_execute array. The array contains the data required to execute the Kiosk.

dataJSON object, optional
Specify the data context for the Kiosk execution. If not provided, the Kiosk will execute without a record context.
- Current_RecordJSON object, optional
  The Current_Record field provides the record context for the Kiosk execution.
  - idstring, optional
    Specify the ID of current record. Use the Get Records API to retrieve the record ID.

Note
If the Current_Record is not provided, any Kiosk state elements that reference the current record such as merge fields, Get Records elements configured to use the current record, or actions like field updates on the current record will return empty values. As a result, these elements or actions may not produce the expected outcome.

Sample Input

Copied{
    "kiosk_execute": [
        {
            "data": {
                "Current_Record": {
                    "id": "5039614000000782064"
                }
            }
        }
    ]
}

Response JSON

The response body is a JSON object containing a kiosk_execute 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 state that is ready to be executed in the Kiosk flow.
  - namestring
    The display name of the next executable state.
  - idlong
    The unique identifier of the next executable state.
- executed_dependent_statesJSON array
  An array of dependent states that were executed automatically after the specified transition. Each object contains information about the executed state and the transition through which it was executed. A dependent state is a non-interactive state that is executed as part of the Kiosk flow before reaching the next executable state.
  - namestring
    The display name of the executed dependent state.
  - idlong
    The unique identifier of the executed dependent state.
  - transitionJSON object
    Contains information about the transition taken from this dependent state.
    - namestring
      The display name of the transition taken.
    - idlong
      The unique identifier of the transition taken.
- idlong
  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. Refer to the Get Kiosk API for the same.
- Invalid current record.
  Resolution: Specify a valid current record ID in the request body. Refer to the Get Records API for the same.
NOT_ALLOWED HTTP 400
- Converted record not supported.
  Resolution: Converted records are not supported. Use the Get Records API to check the value of the Converted__s field and execute the Kiosk using a record whose Converted__s value is false.
- Kiosk not published.
  Resolution: Publish the Kiosk before executing or updating its execution.
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.
MANDATORY_NOT_FOUND HTTP 404
Required field not found.
Resolution: Specify kiosk_execute array in request body. Check the Input JSON section.
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.

Sample Response

Copied{
    "kiosk_execute": [
        {
            "code": "SUCCESS",
            "details": {
                "next_executable_state": {
                    "name": "Screen 1",
                    "id": "5039614000000951848"
                },
                "executed_dependent_states": [
                    {
                        "name": "Decision 1",
                        "id": "5039614000000951843",
                        "transition": {
                            "name": "Path 1",
                            "id": "5039614000000951853"
                        }
                    }
                ],
                "id": "5039614000000947064"
            },
            "message": "Kiosk transition executed successfully",
            "status": "success"
        }
    ]
}