Wizards API
A Wizard helps you divide a long form into a series of screens, where users can enter data on each screen as they proceed to the next step until completion. Wizards reduce the chances of errors during data entry as the screens can be partially saved as a draft and submitted later. For more details, refer to Wizards in Zoho CRM.
Purpose
To get the details of the wizards in a module.
Request Details
Request URL
All wizards - {api-domain}/crm/{version}/settings/wizards
Layout-specific wizard - {api-domain}/crm/{version}/settings/wizards/{wizard_ID}?layout_id={layout_ID}
Supported modules
Leads, Contacts, Deals, Accounts, and custom
Header
Authorization: Zoho-oauthtoken <access_token>
Scope
Scope = ZohoCRM.settings.wizards.READ
Parameters
- layout_idstring, mandatory when you want to fetch a layout-specific wizard
The ID of the layout that you want to fetch the wizard's details from. Use the Layouts MetaData API to obtain the ID of the layout.
Note
- When you set up conditional rules for a wizard, the response contains the keys execute_on and type.
- execute_on represents when the conditional rule is executed. The values are create, edit, and create_edit.
- type represents the action you want to take when the condition is met. The values are set_values, set_lock, show_component, and show_widget.
- When type=set_lock, the response contains the key exempted_profiles. This array contains the list of profiles that allow edits even after locking specific fields.
- The color_palette key is added that displays the colors available for a button on a screen. Note that this key is available in the response only if you have chosen at least one custom color for the button on a screen.
- The following are the changes made to this API from version 5 when you fetch a specific wizard in a layout:
- A new JSON array portal_user_types is added to the response that displays the list of portal user types that have access to the buttons in the wizard.
- A new JSON array exempted_portal_user_types is added to the response that represents the list of portal user types that have access to buttons in wizards that are blocked for other user types.
- Under the segments, for buttons, the Profiles JSON array is added. This indicates the profiles that have access to that button in that screen.
- In the Screens JSON array, the "type" of segments JSON object is changed from fields to composite.
- In the segments JSON array, the fields JSON array is renamed to elements.
- Each object in the elements JSON array contains the sequence number, resource, and type keys. resource includes the "name" and "id" of the field or the query component on the screen. type indicates whether the resource is a field or query_component.
Sample Request to Get All Wizards in a Module
Copiedcurl "https://www.zohoapis.com/crm/v5/settings/wizards"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response
Copied{
"wizards": [
{
"created_time": "2021-02-16T14:51:28+05:30",
"modified_time": "2022-11-16T05:58:29+05:30",
"module": {
"api_name": "Leads",
"id": "3652397000000002175"
},
"name": "wizard 2 leads",
"modified_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "3652397000000026011"
},
{
"display_label": "admin clone",
"name": "admin clone",
"id": "3652397000005787196"
},
{
"display_label": "Sales Manager",
"name": "Sales Manager",
"id": "3652397000009590009"
}
],
"active": true,
"containers": [
{
"layout": {
"name": "Standard",
"id": "3652397000000091055"
},
"id": "3652397000000091055"
}
],
"id": "3652397000003875019",
"created_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
}
},
{
"created_time": "2021-01-21T06:28:21+05:30",
"modified_time": "2021-01-21T06:28:21+05:30",
"module": {
"api_name": "Leads",
"id": "3652397000000002175"
},
"name": "wizard1",
"modified_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "3652397000000026011"
},
{
"display_label": "Standard",
"name": "Standard",
"id": "3652397000000026014"
},
{
"display_label": "Free",
"name": "Free",
"id": "3652397000001614008"
},
{
"display_label": "admin clone",
"name": "admin clone",
"id": "3652397000005787196"
},
{
"display_label": "Sales Manager",
"name": "Sales Manager",
"id": "3652397000009590009"
},
{
"display_label": "test23_$",
"name": "test23_$",
"id": "3652397000009593001"
}
],
"active": true,
"containers": [
{
"layout": {
"name": "Standard",
"id": "3652397000000091055"
},
"id": "3652397000000091055"
}
],
"id": "3652397000003677001",
"created_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
}
},
{
"created_time": "2021-01-21T07:11:06+05:30",
"modified_time": "2021-01-21T07:11:06+05:30",
"module": {
"api_name": "Contacts",
"id": "3652397000000002179"
},
"name": "wizard2",
"modified_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "3652397000000026011"
},
{
"display_label": "admin clone",
"name": "admin clone",
"id": "3652397000005787196"
},
{
"display_label": "Sales Manager",
"name": "Sales Manager",
"id": "3652397000009590009"
}
],
"active": true,
"containers": [
{
"layout": {
"name": "Standard",
"id": "3652397000000091033"
},
"id": "3652397000000091033"
}
],
"id": "3652397000003677031",
"created_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
}
}
]
}Possible Errors
- REQUIRED_PARAM_MISSINGHTTP 400
You have not specified the layout ID in the request.
Resolution: "layout_id" is a mandatory parameter when you want to fetch the details of a particular wizard in a module.
- OAUTH_SCOPE_MISMATCHHTTP 401
You do not have the scope required to use this API.
Resolution: Use the correct scope and generate the grant and access tokens to use this API. - NO_PERMISSIONHTTP 403
You do not have permission to use this API.
Resolution: Contact your administrator.
Sample Request to Get a Layout-specific Wizard
Copiedcurl "https://www.zohoapis.com/crm/v5/settings/wizards/3652397000003875019?layout_id=3652397000000091055"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response
Copied{
"wizards": [
{
"created_time": "2021-02-16T14:51:28+05:30",
"modified_time": "2023-06-28T16:53:30+05:30",
"portal_user_types": null,
"module": {
"api_name": "Leads",
"id": "3652397000000002175"
},
"name": "wizard 2 leads",
"modified_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "3652397000000026011"
},
{
"display_label": "admin clone",
"name": "admin clone",
"id": "3652397000005787196"
},
{
"display_label": "Sales Manager",
"name": "Sales Manager",
"id": "3652397000009590009"
}
],
"active": true,
"containers": [
{
"layout": {
"name": "Standard",
"id": "3652397000000091055"
},
"chart_data": {
"nodes": [
{
"pos_y": 30,
"pos_x": 280,
"start_node": true,
"screen": {
"display_label": "Screen 1",
"id": "3652397000003875021"
}
},
{
"pos_y": 70,
"pos_x": 709,
"start_node": false,
"screen": {
"display_label": "Screen 2",
"id": "3652397000003875023"
}
},
{
"pos_y": 346,
"pos_x": 553,
"start_node": false,
"screen": {
"display_label": "Screen 3",
"id": "3652397000007571009"
}
},
{
"pos_y": 250,
"pos_x": 437,
"start_node": false,
"screen": {
"display_label": "Screen 4",
"id": "3652397000007571011"
}
}
],
"connections": [
{
"source_screen": {
"display_label": "Screen 1",
"id": "3652397000003875021"
},
"target_screen": {
"display_label": "Screen 2",
"id": "3652397000003875023"
},
"id": "3652397000003875063"
},
{
"source_screen": {
"display_label": "Screen 2",
"id": "3652397000003875023"
},
"target_screen": {
"display_label": "Screen 3",
"id": "3652397000007571009"
},
"id": "3652397000007571045"
},
{
"source_screen": {
"display_label": "Screen 3",
"id": "3652397000007571009"
},
"target_screen": {
"display_label": "Screen 4",
"id": "3652397000007571011"
},
"id": "3652397000007571047"
}
],
"color_palette": {
"button_background": [
"#9A2E47",
"#720D5D",
"#FEDBD0",
"#FF0266",
"#25B52A"
]
}
},
"screens": [
{
"display_label": "Screen 3",
"api_name": "Screen_3",
"id": "3652397000007571009",
"segments": [
{
"sequence_number": 1,
"display_label": "Segment3",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Industry",
"id": "3652397000000002613"
},
"type": "field"
}
],
"id": "3652397000007571013",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": null,
"target_screen": {
"name": "Screen 4",
"id": "3652397000007571011"
},
"type": "transition",
"transition": {
"name": "Next",
"id": "3652397000007571001"
},
"sequence_number": 1,
"display_label": "Next",
"background_color": "#1161B5",
"name": "WB_Next_1",
"id": "3652397000007571021",
"category": "wizard_button"
}
],
"column_count": 2,
"id": "3652397000007571019",
"type": "buttons"
}
]
},
{
"display_label": "Screen 4",
"api_name": "Screen_4",
"id": "3652397000007571011",
"segments": [
{
"sequence_number": 1,
"display_label": "Segment 4",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Email_Opt_Out",
"id": "3652397000000014177"
},
"type": "field"
}
],
"id": "3652397000007571027",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": null,
"target_screen": null,
"type": "save",
"message": {
"title": "Save",
"content": "Saved"
},
"transition": null,
"sequence_number": 1,
"display_label": "Save",
"background_color": "#1161B5",
"name": "WB_Save",
"id": "3652397000007571035",
"category": "wizard_button"
}
],
"column_count": 2,
"id": "3652397000007571033",
"type": "buttons"
}
]
},
{
"display_label": "Screen 1",
"api_name": "Screen_1",
"id": "3652397000003875021",
"conditional_rules": [
{
"query_id": "3652397000007463009",
"criteria": {
"comparator": "not_equal",
"field": {
"api_name": "Email",
"id": "3652397000000002599"
},
"value": "${EMPTY}"
},
"actions": [
{
"field": {
"api_name": "First_Name",
"id": "3652397000000002593"
},
"id": "3652397000007463019",
"type": "show_fields"
},
{
"field": {
"api_name": "First_Name",
"id": "3652397000000002593"
},
"id": "3652397000007463021",
"type": "set_mandatory"
},
{
"segment": {
"display_label": "Subform 2",
"id": "3652397000007463003"
},
"id": "3652397000007463023",
"type": "show_subforms"
}
],
"execute_on": "create_edit"
}
],
"segments": [
{
"sequence_number": 1,
"display_label": "Segment Title",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Last_Name",
"id": "3652397000000002595"
},
"type": "field"
},
{
"sequence_number": 3,
"resource": {
"name": "First_Name",
"id": "3652397000000002593"
},
"type": "field"
},
{
"sequence_number": 3,
"resource": {
"name": "Salutation",
"id": "3652397000000022011"
},
"type": "field"
},
{
"sequence_number": 5,
"resource": {
"name": "Email",
"id": "3652397000000002599"
},
"type": "field"
}
],
"id": "3652397000003875025",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Subform 2",
"column_count": 2,
"id": "3652397000007463003",
"type": "subforms",
"fields": [
{
"id": "3652397000000701093"
}
]
},
{
"sequence_number": 3,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "3652397000000026011"
},
{
"display_label": "Sales Manager",
"name": "Sales Manager",
"id": "3652397000009590009"
}
],
"target_screen": {
"name": "Screen 2",
"id": "3652397000003875023"
},
"type": "transition",
"transition": null,
"sequence_number": 1,
"display_label": "Next",
"background_color": "#1161B5",
"name": "WB_Next",
"id": "3652397000003875035",
"category": "wizard_button"
}
],
"column_count": 2,
"id": "3652397000003875037",
"type": "buttons"
}
]
},
{
"display_label": "Screen 2",
"api_name": "Screen_2",
"id": "3652397000003875023",
"segments": [
{
"sequence_number": 1,
"display_label": "Segment Title",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Owner",
"id": "3652397000000002589"
},
"type": "field"
},
{
"sequence_number": 3,
"resource": {
"name": "Lead_Status",
"id": "3652397000000002611"
},
"type": "field"
}
],
"id": "3652397000003875045",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": null,
"target_screen": {
"name": "Screen 3",
"id": "3652397000007571009"
},
"type": "transition",
"transition": null,
"sequence_number": 1,
"display_label": "Next",
"background_color": "#1161B5",
"name": "WB_Next_2",
"id": "3652397000007571041",
"category": "wizard_button"
}
],
"column_count": 2,
"id": "3652397000003875055",
"type": "buttons"
}
]
}
],
"id": "3652397000000091055"
}
],
"id": "3652397000003875019",
"created_by": {
"name": "Patricia Boyle",
"id": "3652397000000186017"
}
}
]
}