Create Webform A/B Testing

Purpose

To create a Webform A/B Test in your Zoho CRM organization.

Webform A/B testing lets you run an experiment where two or more variations of a webform are shown to different segments of your website visitors, so you can compare their performance and identify the version that delivers the best results. This API creates the A/B test — you specify the base (original) webform, one or more variant webforms, the target traffic split, and how long the test should run.

Key terminology

Original form: the existing webform you want to run the A/B test on. Referenced by base_form in the request.
Variant: a modified version of the original webform used for comparison. Configured under variant_form.
Conversion rate: the percentage of visitors who submitted the webform.
Winner: the webform with the highest conversion rate at the end of the test.

Endpoints

POST /settings/AB_testing

Request Details

Request URL

{api-domain}/crm/{version}/settings/AB_testing

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Parameters

modulestring, mandatory
Specify the module for which the webform A/B testing configurations is created.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/AB_testing?module="Leads" 
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X POST
-d "@createwebformabtesting.json"

Input JSON

The request body must be a JSON object with the root key AB_testing, containing an array of Webform A/B test configuration objects.

name string, mandatory
Specify the name of the Webform A/B test. The name must be unique within the module.
traffic integer, mandatory
Specify the overall percentage of visitors to be included in the Webform A/B test.
notify Boolean, optional
Specify whether to receive an email notification with the A/B test winner once the test is completed.
status string, mandatory
Specify the initial status of the A/B test.
Possible values
- drafted: A preliminary version of the A/B test that has been configured but not yet executed.
- running: The test starts immediately and is currently in progress.
- scheduled: The test is scheduled to start in the future, at the time specified in the condition object.
Note: The following lifecycle statuses are returned by read/get APIs but are not accepted when creating a test:
- paused: An ongoing A/B test that has been temporarily put on hold. While paused, the original webform is displayed to all visitors.
- completed: The A/B test has finished running.
- launched: A winning webform has been launched to replace the original.
dynamic_allocation_by_zia Boolean, optional
Specify whether traffic should be dynamically allocated across the base and variant forms based on form performance (powered by Zia).
If enabled, during the test the system dynamically increases the visitor allocation in favor of better-performing variations.
module JSON object, mandatory
Specify the CRM module for which the A/B test is being created. At least one of api_name or id must be specified inside this object.
- idstring, optional
  Specify the unique ID of the module.
- api_namestring, optional
  Specify the API name of the module.
base_form JSON object, mandatory
Specify the base webform used for the A/B test. The base form is the existing (original) webform that variants are compared against.
- idstring, mandatory
  Specify the unique ID of the base webform.
- trafficinteger, optional
  Specify the percentage of traffic allocated to the base form.

condition JSON object, mandatory

Specify how the A/B test duration is determined. The type key inside this object controls which additional fields must be provided.

Supported values for type and their companion fields:

type	Meaning	Required companion fields
duration	Run the A/B test for a fixed duration.	period, unit
range	Run the A/B test between specific start and end date-times.	from, to
visits	Run the A/B test until a specified number of visitors is reached.	unit

Field descriptions

period string: The unit of time. Supported values: days, weeks, months.
unit integer: When type is duration, the number of periods for which the test should run. When type is visits, the total number of visitors after which the test ends.
from string: The start date and time of the A/B test (ISO 8601).
to< /strong> string: The end date and time of the A/B test (ISO 8601).

Validated limits

When period is days: unit ≤ 90
When period is weeks: unit ≤ 12
When period is months: unit ≤ 3
When type is visits: unit ≤ 100000

variant_form JSON array, mandatory
Specify the variant webforms to be created and used in this A/B test. A maximum of 2 variant objects can be provided.
Each variant is a modified version of the base webform used for comparison in the test. Variant forms are configured and created as part of this A/B test setup — they are not pre-existing webforms referenced by ID.
- traffic integer, mandatory
  Specify the percentage of traffic allocated to this variant form.
- form_attributes JSON object, optional
  Specify the visual and layout attributes of this variant webform.
  - color string, optional
    Specify the background color of the variant form.
  - width integer, optional
    Specify the width of the variant form in pixels. Supported values: 600, 700, 800, 900.
  - display_form_name Boolean, optional
    Specify whether the form name should be displayed on the variant webform.
  - align string, optional
    Specify the alignment of the form on the web page.
  - font_attributes JSON object, optional
    Specify the font styling applied to the variant form.
    - size integer, optional
      Specify the font size used in the form.
    - color string, optional
      Specify the font color used in the form.
    - family string, optional
      Specify the font family used in the form.
- button_attributes JSON array, mandatory
  Specify the properties of the action buttons displayed in the variant form.
  - name string, mandatory
    Specify the label displayed on the button.
  - color string, optional
    Specify the color of the button.
- form_fields JSON array, mandatory
  Specify the fields configured for this variant webform. Each object in the array represents one field and defines how it is displayed, validated, and mapped to a CRM field.
  - type string, mandatory
    Specify the category of the form field.
    Supported values:
    - general – Standard CRM fields (for example, Name, Email, Company).
    - advanced – Special fields such as file upload, captcha, or privacy policy. Advanced fields use the field_info object to describe their metadata.
    - portal – Portal-related fields such as Password and Confirm Password.
  - help JSON object, optional
    Specify the help information shown to users while filling the form.
    - text string – The help text to be displayed near the field. Mandatory if the help key is specified.
    - url string – An optional link for additional information.
  - field JSON object, mandatory
    Specify the CRM field to which this webform field is mapped. Used for fields of type general and portal.
    - api_name string – The API name of the CRM field.
    - field_label string – The label displayed on the webform.
    - id string – The unique ID of the CRM field.
  - field_info JSON object, optional
    Specify metadata for advanced fields such as file upload, captcha, or privacy policy fields. This object is used instead of field when type is advanced.
  - hidden Boolean, optional
    Specify whether the field is hidden from users.
    - true – Field is hidden.
    - false – Field is visible.
  - default_value string, optional
    Specify the default value for a hidden field.
  - date_format string, optional
    Specify the date format for date-type fields (for example, DD/MM/YYYY).
  - requiredBoolean, optional
    Specify whether the field is mandatory for form submission.
    - true – Field must be filled.
    - false – Field is optional.
  - display_label string, optional
    Specify a custom label to display on the webform instead of the default CRM field label.
winner_configuration JSON object, optional
Specify how the winning webform should be announced and launched. The webform with the highest conversion rate is considered the winner of the A/B test.
- announce_automaticallyBoolean, optional
  Specify whether the winner should be automatically launched (used across all locations of the original form) once the test is completed.
- conversion_percentage_differenceinteger, optional
  Specify the minimum conversion rate (as a percentage) that a variant must achieve before it is eligible to be launched automatically. This corresponds to the "Based on Condition" option in the A/B testing configuration UI — the winner is launched automatically only if the specified conversion rate is achieved.

Notes

Only one A/B test can be in the Running state at a time.
Ensure that the previous A/B test is in the Launched state before creating a new one.
Variant forms are configured and created as part of this A/B test setup.
The behavior at create time depends on status:
- running – the test starts immediately.
- drafted – the test is saved as a draft.
- scheduled – the test starts at the configured time in the condition object.
The test end criteria (specified in the condition object) can be one of three options: after a specified number of days (duration), after a specified number of visitors (visits), or a specific date range (range).
If dynamic_allocation_by_zia is enabled, the system dynamically increases the visitor allocation in favour of better-performing variations during the test.
Once the test ends, only the original (base) webform is served in all its locations by default, until a winning variant is explicitly launched.
The webform with the highest conversion rate is considered the winner. If multiple webforms have the same conversion rate, the winner is decided using this tie-breaker order:
1. Minimum abandonment rate
2. Highest complete submission rate
3. Original form
If the conversion rate is 0 for all webforms, no winner is declared and the notification email (if notify is enabled) is not sent.
A/B testing is supported only for webforms hosted using the Embed or iFrame format. For Zoho Sites CRM forms, only manual embed is supported (not element-embedded forms).
Once an A/B test has started, its configuration and variants cannot be edited.
Both notify and winner_configuration.announce_automatically are optional.
Lifecycle statuses returned by read APIs may include drafted, scheduled, running, paused, completed, and launched. Only drafted, running, and scheduled are accepted when creating a test.

Traffic allocation

The request accepts three traffic-related values:

traffic at the root of the A/B test object – the overall percentage of visitors included in the test.
base_form.traffic – the percentage of test traffic sent to the base webform.
variant_form[].traffic – the percentage of test traffic sent to each variant webform.

Rules:

The sum of base_form.traffic and all variant_form[].traffic values must equal 100.
The minimum value for any individual traffic allocation is 5.

Sample Input

Copied{
  "AB_testing": [
    {
      "name": "newtestab",
      "traffic": 100,
      "notify": false,
      "status": "running",
      "dynamic_allocation_by_zia": false,

      "module": {
        "api_name": "Leads",
        "id": "4794410000000000125"
      },

      "base_form": {
        "id": "4794410000000765145",
        "traffic": 34
      },

      "condition": {
        "type": "duration",
        "period": "days",
        "unit": 30
      },

      "variant_form": [
        {
          "traffic": 33,

          "form_attributes": {
            "color": "white",
            "width": 600,
            "display_form_name": true,
            "align": "left",
            "font_attributes": {
              "size": 12,
              "color": "black",
              "family": "Arial"
            }
          },

          "button_attributes": [
            { "name": "Submit", "color": "#fff" },
            { "name": "Reset", "color": "#fff" }
          ],

          "form_fields": [
            {
              "type": "general",
              "hidden": false,
              "required": true,
              "field": {
                "api_name": "Company",
                "field_label": "Company",
                "id": "4794410000000000555"
              }
            },
            {
              "type": "general",
              "hidden": false,
              "required": true,
              "field": {
                "api_name": "Last_Name",
                "field_label": "Last Name",
                "id": "4794410000000000559"
              }
            },
            {
              "type": "general",
              "hidden": false,
              "required": false,
              "date_format": "DD/MM/YYYY",
              "field": {
                "api_name": "Date_1",
                "field_label": "Date 1",
                "id": "4794410000000755001"
              }
            },
            {
              "type": "advanced",
              "hidden": false,
              "required": false,
              "field_info": {
                "type": "file_upload",
                "field_label": "Upload a File"
              }
            },
            {
              "type": "advanced",
              "hidden": false,
              "required": false,
              "field_info": {
                "type": "privacy_policy",
                "field_label": "Privacy Policy",
                "privacy_value": "I agree to the Privacy Policy and Terms of Service"
              }
            }
          ]
        },
        {
          "traffic": 33,

          "form_attributes": {
            "color": "white",
            "width": 600,
            "display_form_name": true,
            "align": "left",
            "font_attributes": {
              "size": 12,
              "color": "black",
              "family": "Arial"
            }
          },

          "button_attributes": [
            { "name": "Submit", "color": "#fff" },
            { "name": "Reset", "color": "#fff" }
          ],

          "form_fields": [
            {
              "type": "general",
              "hidden": false,
              "required": true,
              "field": {
                "api_name": "Company",
                "field_label": "Company",
                "id": "4794410000000000555"
              }
            },
            {
              "type": "general",
              "hidden": false,
              "required": true,
              "field": {
                "api_name": "Last_Name",
                "field_label": "Last Name",
                "id": "4794410000000000559"
              }
            },
            {
              "type": "general",
              "hidden": true,
              "required": false,
              "default_value": "hidden",
              "field": {
                "api_name": "Single_Line_1",
                "field_label": "Single Line 1",
                "id": "4794410000000755018"
              }
            },
            {
              "type": "advanced",
              "hidden": false,
              "required": false,
              "field_info": {
                "type": "standard_captcha",
                "field_label": "Enter the Captcha"
              }
            }
          ]
        }
      ],

      "winner_configuration": {
        "announce_automatically": false
      }
    }
  ]
}

Possible Errors

INVALID_DATAHTTP 400
Invalid data type or structure for the AB_testing request body.
Resolution: Ensure the request body follows the correct JSON array format and maximum length constraints.
PATTERN_NOT_MATCHEDHTTP 400
The value provided does not match the expected pattern (for example, an invalid A/B test name).
Resolution: Verify that the field values follow the supported pattern and constraints.
DUPLICATE_DATAHTTP 400
An A/B test with the same name already exists in the module.
Resolution: Use a unique name for the A/B test.
INVALID_DATAHTTP 400
Traffic percentage is outside the allowed range.
Resolution: Ensure each individual traffic value is at least 5, and that base_form.traffic plus all variant_form[].traffic values sum to 100.
INVALID_DATAHTTP 400
Invalid base Webform ID provided.
Resolution: Specify a valid Webform ID that belongs to the given module.
INVALID_DATAHTTP 400
Duration exceeds the allowed limit for the selected period.
Resolution:
- Days must be ≤ 90
- Weeks must be ≤ 12
- Months must be ≤ 3
INVALID_DATAHTTP 400
Visitor limit exceeds the maximum allowed value (100000).
Resolution: Specify a visitor count less than or equal to 100000.
INVALID_DATAHTTP 400
Invalid field ID provided for a variant form field.
Resolution: Ensure that all field IDs belong to the specified module and Webform.
CANNOT_CREATEHTTP 400
A previously created A/B test is not yet launched.
Resolution: Ensure that the previous A/B test is in the Launched state before creating a new one.
REQUIRED_PARAM_MISSINGHTTP 400
Required parameter module is missing.
Resolution: Specify the module query parameter with a valid module API name.

Sample Response

Copied{
    "AB_testing": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "4794410000000772172"
            },
            "message": "ABTesting details created successfully",
            "status": "success"
        }
    ]
}