Update Webform A/B Testing

Parameters

• modulestring, mandatory

  Specify the module API name to which the A/B testing belongs. The module of an existing A/B test cannot be changed — the value supplied here must match the module the test was originally created for.

Input JSON keys

The request body must be a JSON object with the root key AB_testing, which is a JSON array containing a single A/B test configuration object with the following keys:

• namestring, mandatory

  Specify the name of the Webform A/B test. The name must be unique within the module.

• trafficinteger, mandatory

  Specify the overall percentage of visitors to be included in the Webform A/B test.

• notifyboolean, optional

  Specify whether to receive an email notification with the A/B test winner once the test is completed.

• statusstring, mandatory

  Specify the desired status of the A/B test after this update.

  Supported values:

  • drafted - A preliminary version of the A/B test that has been configured but not yet executed.
  • running - The test is currently in progress. Use this value to start a drafted test, launch a scheduled test early, or resume a paused test.
  • scheduled - The test is scheduled to start in the future, at the time specified in the condition object.
  • paused - The test has been temporarily put on hold. Applicable only to tests that are currently running. While paused, the original webform is displayed to all visitors and metrics collected so far are preserved.

  The lifecycle statuses completed and launched are returned by read APIs but cannot be set through this API. The paused status is accepted for updates but not when creating a test.

• dynamic_allocation_by_ziaboolean, 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 favour of better-performing variations.

• moduleJSON object, mandatory

  Specify the CRM module to which the A/B test belongs. At least one of api_name or id must be specified. The module of an existing A/B test cannot be changed; the value supplied here must match the module the test was originally created for.

  • idstring, optional

    Specify the unique ID of the module.

  • api_namestring, optional

    Specify the API name of the module.

• base_formJSON object, mandatory

  Specify the base webform used for the A/B test. The base webform (identified by id) of an existing A/B test cannot be changed; only its traffic allocation can be updated (subject to state restrictions).

  • idstring, mandatory

    Specify the unique ID of the base webform. Must match the base form the test was originally created with.

  • trafficinteger, optional

    Specify the percentage of traffic allocated to the base form.

• conditionJSON object, mandatory

  Specify how the A/B test duration is determined. The type key inside this object controls which additional fields must be provided. For scheduled tests, updating this object is how you change the planned start and end date-times.

  • typestring, mandatory

    Specify how the test duration is determined.

    Supported values:

    • duration – Run the A/B test for a fixed duration. Requires period and unit.
    • range – Run the A/B test between specific start and end date-times. Requires from and to.
    • visits – Run the A/B test until a specified number of visitors is reached. Requires unit.
  • periodstring, optional

    Specify the unit of time when type is duration.

    Supported values:

    • days – Maximum unit value is 90.
    • weeks – Maximum unit value is 12.
    • months – Maximum unit value is 3.
  • unitinteger, optional

    When type is duration, specify the number of periods for which the test should run. When type is visits, specify the total number of visitors after which the test ends (maximum 100000).

  • fromdatetime, optional

    Specify the start date and time of the A/B test in ISO 8601 format. Applicable when type is range. Can be updated for tests in scheduled state.

  • todatetime, optional

    Specify the end date and time of the A/B test in ISO 8601 format. Applicable when type is range. Can be updated for tests in scheduled state.

• variant_formJSON array, mandatory

  Specify the variant webforms used in this A/B test. A maximum of 2 variant objects can be provided. Variants can only be modified while the test is in drafted or scheduled state.

  • trafficinteger, mandatory

    Specify the percentage of traffic allocated to this variant form.

  • form_attributesJSON object, optional

    Specify the visual and layout attributes of this variant webform.

    • colorstring, optional

      Specify the background color of the variant form.

    • widthinteger, optional

      Specify the width of the variant form in pixels. Supported values: 600, 700, 800, 900.

    • display_form_nameboolean, optional

      Specify whether the form name should be displayed on the variant webform.

    • alignstring, optional

      Specify the alignment of the form on the web page.

    • font_attributesJSON object, optional

      Specify the font styling applied to the variant form.

      • sizeinteger, optional

        Specify the font size used in the form.

      • colorstring, optional

        Specify the font color used in the form.

      • familystring, optional

        Specify the font family used in the form.

  • button_attributesJSON array, mandatory

    Specify the properties of the action buttons displayed in the variant form.

    • namestring, mandatory

      Specify the label displayed on the button.

    • colorstring, optional

      Specify the color of the button.

  • form_fieldsJSON 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.

    • typestring, 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.
    • helpJSON object, optional

      Specify the help information shown to users while filling the form.

      • textstring, mandatory

        Specify the help text to be displayed near the field. Mandatory if the help key is specified.

      • urlstring, optional

        Specify an optional link for additional information.

    • fieldJSON object, mandatory

      Specify the CRM field to which this webform field is mapped. Used for fields of type general and portal.

      • api_namestring, optional

        Specify the API name of the CRM field.

      • field_labelstring, optional

        Specify the label displayed on the webform.

      • idstring, optional

        Specify the unique ID of the CRM field.

    • field_infoJSON 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.

    • hiddenboolean, optional

      Specify whether the field is hidden from users.

      Supported values:

      • true – Field is hidden.
      • false – Field is visible.
    • default_valuestring, optional

      Specify the default value for a hidden field.

    • date_formatstring, 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.

      Supported values:

      • true – Field must be filled.
      • false – Field is optional.
    • display_labelstring, optional

      Specify a custom label to display on the webform instead of the default CRM field label.

• winner_configurationJSON 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.

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

  Another 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, or the base form ID does not match the base form the test was originally created with.
  Resolution: Specify the same base base_form.id the test was created with. The base form of an existing A/B test cannot be changed.

• INVALID_DATAHTTP 400

  Attempt to change the module of an existing A/B test.
  Resolution: The module of an existing A/B test cannot be updated. Supply the module (both in the query parameter and in the request body) that the test was originally created for.

• 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.

• INVALID_DATAHTTP 400

  Invalid status transition (for example, attempting to set status to paused for a test that is not currently running, or trying to move a completed/launched test back to running).
  Resolution: Use a status transition supported for the test's current state (see the "State-based restrictions" section).

• NOT_ALLOWEDHTTP 400

  Attempt to edit fields (such as condition, variant_form, or traffic split) that cannot be modified in the test's current state (for example, while the test is running, paused, completed, or launched).
  Resolution: Only update fields that are editable in the current state, or move the test to drafted/scheduled where applicable before making structural changes.

• INVALID_DATAHTTP 400

  Invalid start/end date-time for a scheduled test (for example, from in the past, or to earlier than from).
  Resolution: Ensure from is in the future and to is later than from, and that both are valid ISO 8601 date-time values.

• REQUIRED_PARAM_MISSINGHTTP 400

  Required parameter module is missing.
  Resolution: Specify the module query parameter with a valid module API name.

• INVALID_URL_PATTERNHTTP 404

  The requested URL is invalid, or the {AB_testing_ID} in the URL does not exist.
  Resolution: Verify the URL path and ensure the A/B test ID is correct.

• OAUTH_SCOPE_MISMATCHHTTP 401

  The access token used does not have the required scope.
  Resolution: Use a token with ZohoCRM.settings.abtest.UPDATE or ZohoCRM.settings.abtest.ALL scope.