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 modules.
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
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 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 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.
- From V6, you can get the list of available screens in Wizards. See the sample response for reference.
Response JSON
- wizardsJSON array
Contains different wizards' details in the CRM. Each wizard has its own set of properties.
- created_timestring
Represents the timestamp when the wizard was created.
- modified_timestring
Represents the timestamp when the wizard was last modified.
- portal_user_typesJSON array
Lists the portal user types that have permissions to access the wizard.
- moduleJSON object
Represents details about the module associated with the wizard.
- api_namestring
Represents the API name of the module.
- idstring
Represents the unique ID of the module.
- namestring
Represents the name of the wizard.
- modified_byJSON object
This object contains information about the user who last modified the wizard.
- namestring
Represents the name of the user.
- idstring
Represents the ID of the user.
- profilesJSON array
This key contains an array of profiles that can access this wizard.
Each profile includes:
- display_label - Represents the display label of the profiles in the UI.
- name - Represents the API name of the profiles.
- id - Represents the unique identifier of the profile.
- activeBoolean
Represents whether the wizard is currently active ("active": true) or not ("active": false).
- containersJSON array
Multiple layouts can be included in a single wizard. The "containers" JSON array lists the layouts included in a wizard along with the respective screens associated with each layout.
- layoutJSON object
Contains details about the layout.
- display_labelstring
Represents the layout's display label as shown in the UI.
- namestring
Represents the API name of the layout.
- idstring
Represents the unique ID of the layout.
- screensJSON array
Includes details of the screens present in each layout.
- display_labelstring
Represents the display label of the screen visible in the UI.
- api_namestring
Represents the API name of the screen.
- idstring
Represents the unique ID of the screen.
- idstring
Represents the unique ID of the layout.
- idstring
Represents the unique ID of the Wizard.
- created_byJSON object
Contains information about who created the wizard, including their name and ID.
Sample Request to Get All Wizards in a Module
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/wizards"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response
Copied{
"wizards": [
{
"created_time": "2024-05-09T23:25:22-07:00",
"modified_time": "2024-05-09T23:25:22-07:00",
"portal_user_types": [
{
"display_label": "ClientPortal",
"name": "ClientPortal",
"id": "5725767000004742018"
}
],
"module": {
"api_name": "Leads",
"id": "5725767000000002175"
},
"name": "Lead",
"modified_by": {
"name": "Patricia Boyle",
"id": "5725767000000411001"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "5725767000000026011"
},
{
"display_label": "Standard",
"name": "Standard",
"id": "5725767000000026014"
},
{
"display_label": "asd",
"name": "asd",
"id": "5725767000000871001"
}
],
"active": true,
"containers": [
{
"layout": {
"display_label": "Standard",
"name": "Standard",
"id": "5725767000000091055"
},
"screens": [
{
"display_label": "Personal",
"api_name": "Personal1",
"id": "5725767000000526327"
},
{
"display_label": "Lead status",
"api_name": "Lead_status1",
"id": "5725767000000526329"
},
{
"display_label": "Income",
"api_name": "Income1",
"id": "5725767000000526331"
}
],
"id": "5725767000000091055"
},
{
"layout": {
"display_label": "Zoho",
"name": "Zoho",
"id": "5725767000000526001"
},
"screens": [
{
"display_label": "Save Page",
"api_name": "Save_Page1",
"id": "5725767000000526395"
},
{
"display_label": "save page2",
"api_name": "save_page21",
"id": "5725767000000526397"
}
],
"id": "5725767000000526001"
}
],
"id": "5725767000000526319",
"created_by": {
"name": "Patricia Boyle",
"id": "5725767000000411001"
}
},
{
"created_time": "2024-12-05T02:58:12-08:00",
"modified_time": "2024-12-05T02:58:12-08:00",
"portal_user_types": [
{
"display_label": "ClientPortal",
"name": "ClientPortal",
"id": "5725767000004742018"
}
],
"module": {
"api_name": "Leads",
"id": "5725767000000002175"
},
"name": "test",
"modified_by": {
"name": "Patricia Boyle",
"id": "5725767000000411001"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "5725767000000026011"
}
],
"active": true,
"containers": [
{
"layout": {
"display_label": "Standard",
"name": "Standard",
"id": "5725767000000091055"
},
"screens": [
{
"display_label": "Screen 1",
"api_name": "Screen_1",
"id": "5725767000004742097"
},
{
"display_label": "Screen 2",
"api_name": "Screen_2",
"id": "5725767000004742099"
},
{
"display_label": "Screen 3",
"api_name": "Screen_3",
"id": "5725767000004742101"
},
{
"display_label": "Screen 4",
"api_name": "Screen_4",
"id": "5725767000004742103"
},
{
"display_label": "Screen 5",
"api_name": "Screen_5",
"id": "5725767000004742105"
},
{
"display_label": "Screen 6",
"api_name": "Screen_6",
"id": "5725767000004742107"
}
],
"id": "5725767000000091055"
}
],
"id": "5725767000004742095",
"created_by": {
"name": "Patricia Boyle",
"id": "5725767000000411001"
}
}
]
}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/v8/settings/wizards/3652397000003875019?layout_id=3652397000000091055"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response
Copied{
"wizards": [
{
"created_time": "2023-12-06T16:56:25+05:30",
"modified_time": "2023-12-06T18:40:27+05:30",
"portal_user_types": null,
"module": {
"api_name": "Leads",
"id": "2423488000000000125"
},
"name": "test",
"modified_by": {
"name": "Patricia",
"id": "2423488000000483001"
},
"profiles": [
{
"display_label": "Administrator",
"name": "Administrator",
"id": "2423488000000015972"
},
{
"display_label": "Standard",
"name": "Standard",
"id": "2423488000000015975"
}
],
"active": true,
"containers": [
{
"layout": {
"name": "Standard",
"id": "2423488000000095055"
},
"chart_data": {
"nodes": [
{
"pos_y": 300,
"pos_x": 618,
"start_node": true,
"screen": {
"display_label": "Screen 1",
"id": "2423488000000709018"
}
},
{
"pos_y": 480,
"pos_x": 998,
"start_node": false,
"screen": {
"display_label": "Screen 2",
"id": "2423488000000709020"
}
},
{
"pos_y": 440,
"pos_x": 1498,
"start_node": false,
"screen": {
"display_label": "Screen 3",
"id": "2423488000000709022"
}
}
],
"connections": [
{
"source_screen": {
"display_label": "Screen 1",
"id": "2423488000000709018"
},
"target_screen": {
"display_label": "Screen 2",
"id": "2423488000000709020"
},
"id": "2423488000000709080"
},
{
"source_screen": {
"display_label": "Screen 2",
"id": "2423488000000709020"
},
"target_screen": {
"display_label": "Screen 3",
"id": "2423488000000709022"
},
"id": "2423488000000709082"
}
],
"color_palette": {
"button_background": [
"#ADD9FF",
"#C4F0B3",
"#FFD6BC",
"#F8E199",
"#FFC6C6"
]
}
},
"screens": [
{
"display_label": "Screen 1",
"api_name": "Screen_1",
"id": "2423488000000709018",
"conditional_rules": null,
"segments": [
{
"sequence_number": 1,
"display_label": "Lead Image",
"tab_traversal": "left_to_right",
"column_count": 1,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Record_Image",
"id": "2423488000000179001"
},
"type": "field"
}
],
"id": "2423488000000712004",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Segment Title",
"tab_traversal": "left_to_right",
"column_count": 2,
"elements": [
{
"sequence_number": 0,
"resource": {
"name": "Salutation",
"id": "2423488000000000601"
},
"type": "field"
},
{
"sequence_number": 1,
"resource": {
"name": "Last_Name",
"id": "2423488000000000559"
},
"type": "field"
},
{
"sequence_number": 3,
"resource": {
"name": "First_Name",
"id": "2423488000000000557"
},
"type": "field"
},
{
"sequence_number": 5,
"resource": {
"name": "Email",
"id": "2423488000000000563"
},
"type": "field"
},
{
"sequence_number": 7,
"resource": {
"name": "Image_Upload",
"id": "2423488000000534029"
},
"type": "field"
}
],
"id": "2423488000000709024",
"type": "composite"
},
{
"sequence_number": 3,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": null,
"target_screen": {
"name": "Screen 2",
"id": "2423488000000709020"
},
"type": "transition",
"transition": null,
"sequence_number": 1,
"display_label": "Screen1",
"background_color": "#00A3F3",
"name": "WB_Screen1",
"id": "2423488000000709038",
"category": "wizard_button"
}
],
"tab_traversal": "left_to_right",
"column_count": 2,
"id": "2423488000000709036",
"type": "buttons"
}
]
},
{
"display_label": "Screen 2",
"api_name": "Screen_2",
"id": "2423488000000709020",
"conditional_rules": null,
"segments": [
{
"sequence_number": 1,
"display_label": "Lead Image",
"tab_traversal": "left_to_right",
"column_count": 1,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Record_Image",
"id": "2423488000000179001"
},
"type": "field"
}
],
"id": "2423488000000712012",
"type": "composite"
},
{
"sequence_number": 2,
"display_label": "Lead came from",
"tab_traversal": "left_to_right",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Lead_Source",
"id": "2423488000000000573"
},
"type": "field"
},
{
"sequence_number": 3,
"resource": {
"name": "Lead_Status",
"id": "2423488000000000575"
},
"type": "field"
}
],
"id": "2423488000000709046",
"type": "composite"
},
{
"sequence_number": 3,
"display_label": "Dummy",
"buttons": [
{
"color": "#fff",
"shape": "square",
"visibility": "show",
"resource": null,
"criteria": null,
"profiles": null,
"target_screen": {
"name": "Screen 3",
"id": "2423488000000709022"
},
"type": "transition",
"transition": null,
"sequence_number": 1,
"display_label": "screen2",
"background_color": "#00A3F3",
"name": "WB_screen2",
"id": "2423488000000709056",
"category": "wizard_button"
}
],
"tab_traversal": "left_to_right",
"column_count": 2,
"id": "2423488000000709054",
"type": "buttons"
}
]
},
{
"display_label": "Screen 3",
"api_name": "Screen_3",
"id": "2423488000000709022",
"conditional_rules": null,
"segments": [
{
"sequence_number": 1,
"display_label": "Revenue",
"tab_traversal": "left_to_right",
"column_count": 2,
"elements": [
{
"sequence_number": 1,
"resource": {
"name": "Annual_Revenue",
"id": "2423488000000000581"
},
"type": "field"
}
],
"id": "2423488000000709064",
"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": null,
"transition": null,
"sequence_number": 1,
"display_label": "Screen 3",
"background_color": "#00A3F3",
"name": "WB_Screen_3",
"id": "2423488000000709072",
"category": "wizard_button"
}
],
"tab_traversal": "left_to_right",
"column_count": 2,
"id": "2423488000000709070",
"type": "buttons"
}
]
}
],
"id": "2423488000000095055"
}
],
"id": "2423488000000709012",
"created_by": {
"name": "Patricia",
"id": "2423488000000483001"
}
}
]
}