Create Kiosk GetRecords

Purpose

This API allows you to create a GetRecords configuration for a specific Kiosk. It defines how records should be fetched from a module, including criteria, selection behavior, and sorting. You can create GetRecords configurations only for Kiosks in the draft state.

Use the Get All Kiosks API to retrieve the Kiosk ID.

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

Permission Required: Administrator profile, or profiles with either the Module Customization or Manage Automation permission enabled.

Endpoints

POST /settings/kiosks/{kiosk_ID}/get_records

Request Details

Request URL

{api-domain}/crm/{version}/settings/kiosks/{kiosk_ID}/get_records

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/kiosks/5725767000010015021/get_records"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@kiosksGetRecord.json"

Input JSON

The get_records JSON array is the root key. It must contain only one object that defines the GetRecords configuration for the specified Kiosk. Provide the following keys within the object.

selection_detailsJSON object, mandatory
Specify the record selection behavior configured for the GetRecords configuration, including whether users can select records, whether a single or multiple records are displayed, and the maximum number of records that can be displayed.
- selection_typestring, mandatory
  Specify how users can interact with the records displayed by the GetRecords configuration during Kiosk execution.
  Possible values:
  mandatory: User must select at least one record.
  optional: User may choose records, but selection is not mandatory.
  read_only: Records are only displayed and cannot be selected.
- result_typestring, mandatory
  Represents the number of records returned by the GetRecords configuration during Kiosk execution.
  Possible values:
  single - Returns a single record.
  multiple - Returns multiple records.
  all - Returns all matching records.
  When result_type is single, the value of limit must be 1.
  When result_type is multiple, the maximum supported value is 100.
- limitinteger, mandatory
  Specify the maximum number of records to fetch.
  Maximum supported value: 100.
- rangeinteger, mandatory
  Specify the range of records to retrieve.
  Maximum supported value: 2000.
  Example:
  If range = 50 and limit = 3:
  The Kiosk fetches 50 records.
  The user can select up to 3 records from them.
criteriaJSON object,mandatory
Provide the criteria configuration to filter the records fetched from the module.
- group_operatorstring, mandatory
  Specify the logical operator used to combine multiple criteria conditions. This key is required only when multiple criteria conditions are provided.
  Possible values: AND, OR.
- groupJSON array, mandatory
  Provide the list of criteria conditions to apply while fetching records. This key is required only when multiple criteria conditions are provided.
  - comparatorstring, mandatory
    Specify the comparison operator to use in the criteria condition. Example: contains, less_equal, equals.
  - fieldJSON object, mandatory
    Provide the field details to use in the criteria condition. Use the Fields Metadata API to retrieve the field details.
    - api_namestring, mandatory
      Specify the API name of the field.
    - idstring, mandatory
      Provide the unique ID of the field.
  - typestring, mandatory
    Specify the criteria type.
    Possible values: value
  - valuestring, mandatory
    Specify the value against which the specified field value of each record is compared when evaluating the criteria.
moduleJSON object, mandatory
Provide the module details from which records must be fetched. Use the Module Metadata API to retrieve the module details.
- api_namestring, mandatory
  Specify the API name of the module.
- idstring, mandatory
  Provide the unique ID of the module.
namestring, mandatory
Specify the name of the GetRecords configuration. The name must be unique within the Kiosk.
typestring, mandatory
Specify whether records are fetched from the parent module or a child module in the Kiosk flow.
Possible values: parent, child.
sort_orderJSON object, mandatory
Provide the configuration to sort the fetched records.
- order_by_namestring, mandatory
  Specify the sorting order.
  Possible values: ascending, descending.
- order_by_fieldJSON object, mandatory
  Provide the field details to sort the records. Any field in the selected module can be used for sorting except Multi-Module Lookup fields.
  - api_namestring, mandatory
    Specify the API name of the sorting field. Use the Fields Metadata API to retrieve the field details.
  - idstring, mandatory
    Provide the unique ID of the sorting field. Use the Fields Metadata API to retrieve the field details.

Note

You cannot configure the GetRecords in an active Kiosk. Only Kiosks in the draft state can be configured or updated. Use the Get All Kiosks API to retrieve Kiosk IDs.
The maximum number of GetRecords configurations allowed per Kiosk depends on the CRM edition:
- Enterprise: 50
- Professional: 10
- Standard: 5

Sample Input

Copied{
    "get_records": [
        {
            "selection_details": { //MANDATORY
                "selection_type": "read_only",
                "result_type": "multiple",
                "limit": 100,
                "range": 100
            },
            "criteria": { //MANDATORY
                "comparator": "contains",
                "field": {
                    "api_name": "Email",
                    "id": "5725767000000002599"
                },
                "type": "value",
                "value": "patricia@mail.com"
            },
            "module": { //MANDATORY
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "name": "Get Lead records", //MANDATORY
            "type": "parent", //MANDATORY
            "sort_order": { //MANDATORY
                "order_by_name": "descending",
                "order_by_field": {
                    "api_name": "Modified_Time",
                    "id": "5725767000000002629"
                }
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- Invalid ID has been given
  Resolution: Specify a valid Kiosk ID. Use the Get All Kiosks API to retrieve the Kiosk ID.
- Invalid field ID or field API name has been given in the criteria or sorting configuration.
  Resolution: Specify valid field details. Use the Fields Metadata API to retrieve the field ID and API name.
- Invalid criteria configuration has been given.
  Resolution: Ensure the comparator, group operator, and criteria structure are valid. Refer to the Input JSON section for more details.
- Invalid selection configuration has been given.
  Resolution: Specify valid values for selection_type and result_type. Refer to the Input JSON section for more details.
- Invalid sorting configuration has been given.
  Resolution: Specify a valid sorting field and order.
- Invalid value has been given for limit or range.
  Resolution: Specify valid positive integer values for limit and range. Refer to the Input JSON section for more details.
LIMIT_EXCEEDEDHTTP 400
The maximum number of GetRecords configurations allowed for your CRM edition has been reached
Resolution: Upgrade your CRM edition to create additional GetRecords configurations.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields are missing
Resolution: Refer to the Input JSON section to know the mandatory fields.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to the Endpoints section for more details.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create the GetRecords configuration for a specific Kiosk. Create a new token with valid scope. Refer to the Scope section for more details.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the Request URL section for more details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "get_records": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000010201002"
            },
            "message": "Get record created successfully",
            "status": "success"
        }
    ]
}