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 in V4 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.

Sample Request to Get All Wizards in a Module

Copiedcurl "https://www.zohoapis.com/crm/v4/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/v4/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": "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"
                    },
                    "chart_data": {
                        "nodes": [
                            {
                                "pos_y": 30,
                                "pos_x": 279,
                                "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,
                                    "id": "3652397000007571013",
                                    "type": "fields",
                                    "fields": [
                                        {
                                            "sequence_number": 1,
                                            "api_name": "Industry",
                                            "id": "3652397000000002613"
                                        }
                                    ]
                                },
                                {
                                    "sequence_number": 2,
                                    "display_label": "Dummy",
                                    "buttons": [
                                        {
                                            "color": "#fff",
                                            "shape": "square",
                                            "visibility": "show",
                                            "resource": null,
                                            "criteria": 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,
                                    "id": "3652397000007571027",
                                    "type": "fields",
                                    "fields": [
                                        {
                                            "sequence_number": 1,
                                            "api_name": "Email_Opt_Out",
                                            "id": "3652397000000014177"
                                        }
                                    ]
                                },
                                {
                                    "sequence_number": 2,
                                    "display_label": "Dummy",
                                    "buttons": [
                                        {
                                            "color": "#fff",
                                            "shape": "square",
                                            "visibility": "show",
                                            "resource": null,
                                            "criteria": 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,
                                    "id": "3652397000003875025",
                                    "type": "fields",
                                    "fields": [
                                        {
                                            "sequence_number": 1,
                                            "api_name": "Last_Name",
                                            "id": "3652397000000002595"
                                        },
                                        {
                                            "sequence_number": 3,
                                            "api_name": "First_Name",
                                            "id": "3652397000000002593"
                                        },
                                        {
                                            "sequence_number": 3,
                                            "api_name": "Salutation",
                                            "id": "3652397000000022011"
                                        },
                                        {
                                            "sequence_number": 5,
                                            "api_name": "Email",
                                            "id": "3652397000000002599"
                                        }
                                    ]
                                },
                                {
                                    "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,
                                            "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,
                                    "id": "3652397000003875045",
                                    "type": "fields",
                                    "fields": [
                                        {
                                            "sequence_number": 1,
                                            "api_name": "Owner",
                                            "id": "3652397000000002589"
                                        },
                                        {
                                            "sequence_number": 3,
                                            "api_name": "Lead_Status",
                                            "id": "3652397000000002611"
                                        }
                                    ]
                                },
                                {
                                    "sequence_number": 2,
                                    "display_label": "Dummy",
                                    "buttons": [
                                        {
                                            "color": "#fff",
                                            "shape": "square",
                                            "visibility": "show",
                                            "resource": null,
                                            "criteria": 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"
            }
        }
    ]
}