Create Blueprint

Request JSON

The Blueprints JSON array is the root element within which all blueprint details required to create a blueprint must be specified. Only one blueprint object can be included in the array per request. The Blueprints JSON array may include the following keys:

• ownersJSON array, optional

  Specify the details of the blueprint owners. This setting can be used to define which users, roles, groups, record owners, or portal user types are associated with or allowed access to the blueprint.

  Conditional requirement: This field is mandatory when continuous is set to true.

  • resourcesJSON array, mandatory

    Specify the resource details of the blueprint owner. Each resource identifies an entity such as a user, role, or group associated with the selected owner type.

    • idstring, mandatory

      Specify the ID of the blueprint owner resource.

  • typestring, mandatory

    Specify the owner type.
    Possible values: users, role, group, record_owner, portal_user_type.
    This determines how the resources array is interpreted.

• criteriaJSON object, optional

  Specify the details of the blueprint entry criteria. Entry criteria determine which records are eligible to enter the blueprint process.

  • comparatorstring, optional

    Specify the comparator used in the criteria expression.
    Possible values: is, isn't, contains, doesn't contain, starts with, ends with, is empty, is not empty.

  • fieldJSON object, optional

    Specify the field details configured in the criteria. This field is evaluated to decide whether the record satisfies the blueprint entry condition.

    • api_namestring, optional

      Specify the API name of the field used in the criteria.

    • idstring, mandatory

      Specify the ID of the field used in the criteria. Use the Fields Metadata API to retrieve this ID.

  • typestring, optional

    Specify what the criteria is based on, such as comparison against a fixed value or another field.

  • valuestring, optional

    Specify the value configured for the criteria comparison when the condition is value-based.

• chart_dataJSON object, optional

  Contains the details of the visual chart representation of the configured blueprint. This section stores the canvas layout used in the Blueprint editor, including node positions, visual connectors, and canvas dimensions.

  Keep chart_data consistent with the logical structure defined in states, transitions, and connections.

  Important: Although optional in schema, chart_data is practically required before first activation so that the blueprint renders correctly in the editor.

  • nodesJSON array, optional

    Contains details of the nodes of the blueprint. Nodes represent the states of the blueprint as displayed in the visual editor.

    • position_xinteger, mandatory

      Position of the node on the x-axis within the blueprint canvas.

    • position_yinteger, mandatory

      Position of the node on the y-axis within the blueprint canvas.

    • stateJSON object, mandatory

      Contains details of the state mapped to the node. In Zoho CRM, a state represents a stage or condition in the business process.

      • api_namestring, mandatory

        Specify the API name of the state represented by the node.

  • canvas_sizeJSON object, mandatory

    Use canvas_size to configure the height and width of the canvas on which the blueprint chart data is displayed in the Blueprint editor.

    • widthinteger, mandatory

      Width of the blueprint chart canvas.

    • heightinteger, mandatory

      Height of the blueprint chart canvas.

  • connectionsJSON array, optional

    Details of the visual connections between nodes in the blueprint chart. These connections represent the graphical flow between states and are associated with transitions.

    • fromJSON object, mandatory

      Details of the source side of the visual connection.

      • end_pointJSON object, mandatory

        Details of the end point of the source side of the connection in the blueprint canvas.

        • position_xdouble, mandatory

          Position of the source point on the x-axis.

        • position_yinteger, mandatory

          Position of the source point on the y-axis.

        • direction_xinteger, mandatory

          Horizontal direction of the connection line from the source point.

        • direction_yinteger, mandatory

          Vertical direction of the connection line from the source point.

      • stateJSON object, mandatory

        Contains state details of the source node from which the connection begins.

        • api_namestring, mandatory

          Specify the API name of the source state.

    • api_namestring, mandatory

      Specify the API name of the visual connection.

    • toJSON object, mandatory

      Details of the target side of the visual connection.

      • end_pointJSON object, mandatory

        End point details of the target side of the connection.

        • position_xinteger, mandatory

          Position of the target point on the x-axis.

        • position_ydouble, mandatory

          Position of the target point on the y-axis.

        • direction_xinteger, mandatory

          Horizontal direction of the connection line toward the target point.

        • direction_yinteger, mandatory

          Vertical direction of the connection line toward the target point.

      • stateJSON object, mandatory

        Contains state details of the target node to which the connection points.

        • api_namestring, mandatory

          Specify the API name of the target state.

    • transitionJSON object, mandatory

      Details of the transition mapped with the connection. In Zoho CRM, a transition is the action that moves a record from one state to another.

      • api_namestring, mandatory

        Specify the API name of the transition associated with the connection.

      • namestring, optional

        Name of the transition shown in the process design.

• continuous Boolean, optional

  Specifies whether the blueprint runs in continuous mode.

  Set to true for continuous execution behavior where records can continue through configured process paths. Set to false for one-time progression behavior through the configured path.

• moduleJSON object, mandatory

  Contains the details of the module for which the blueprint is configured. A blueprint in Zoho CRM always applies to a specific module and governs the records in that module.

  Provide either id or api_name based on metadata availability. Use the Modules Metadata API to retrieve valid module identifiers.

  • api_namestring, optional

    Specify the API name of the module.

  • idstring, mandatory

    Specify the ID of the module. Use the Modules Metadata API to retrieve this ID.

  • precedenceinteger, optional

    Specify the precedence of the module where applicable in the configuration.

• pipelineJSON object, optional

  Contains the details of the pipeline for which the blueprint is configured. This is applicable only for the Deals module and is used when the blueprint should apply only to records in a specific sales pipeline.

  • idstring, mandatory

    Specify the ID of the pipeline.

  • api_namestring, optional

    Specify the API name of the pipeline.

  • display_valuestring, optional

    Specify the display value of the pipeline as shown in the CRM UI.

• transitionsJSON array, optional

  Specify the transitions associated with the blueprint. A transition is the action or step that moves a record from one state to another. Transitions can be manual or automatic, may require inputs during execution, and can trigger automation after completion.

  • criteriaJSON object, optional

    Specify the criteria configured for displaying or allowing the transition. This determines whether the transition is available based on record data.

    • comparatorstring, mandatory

      Specify the comparator of the criteria.

    • fieldJSON object, mandatory

      Specify field details configured in the criteria.

      • api_namestring, optional

        Specify the API name of the field.

      • idstring, mandatory

        Specify the ID of the field. Use the Fields Metadata API to retrieve this ID.

    • typestring, mandatory

      Specify whether the criteria compares against a value or another field.

    • valuestring, optional

      Specify the value used in the criteria comparison.

  • trigger_typestring, mandatory

    Specify whether the transition is triggered manually or automatically.
    Possible values: manual, automatic.
    Automatic transitions move the record after a configured wait time in the current state.

  • moduleJSON object, optional

    Specify module details for which the transition is configured.

    • api_namestring, optional

      Specify the API name of the module.

    • idstring, mandatory

      Specify the ID of the module. Use the Modules Metadata API to retrieve this ID.

  • layoutJSON object, optional

    Specify the details of the layout context for the transition.

    • api_namestring, optional

      Specify the API name of the layout.

    • namestring, optional

      Specify the name of the layout.

    • idstring, optional

      Specify the ID of the layout. Use the Layouts Metadata API to retrieve this ID.

  • descriptionstring, optional

    Description of the transition and its business purpose within the process flow.

  • ownersJSON array, optional

    Specify the details of the owners for whom the transition is accessible. This controls who can execute the transition.

    • resourcesJSON array, optional

      Specify the details of the transition owners.

      • idstring, optional

        Specify the ID of the transition owner.

    • typestring, optional

      Specify the type of the owner.
      Possible values: users, role, group, record_owner, portal_user_type.

  • commonBoolean, optional

    Specify whether the transition is a common transition. A common transition can be made available from multiple source states.

  • include_statesJSON array, optional

    Specify the details of the common source states for the transition when the transition is configured as common.

    • stateJSON object, optional

      Specify the state details of the common source.

      • namestring, optional

        Specify the name of the state.

      • api_namestring, optional

        Specify the API name of the state.

  • during_inputsJSON array, optional

    List of the fields configured during the transition. This defines what a user must do at the exact moment they click a transition button to advance a record. It acts as a mandatory validation checkpoint that enforces data collection and process compliance before the record updates to the next stage.

    • validation_filterJSON object, optional

      Details of validation configured for the during-transition fields. If validation fails, the transition cannot be completed.

      • criteriaJSON object, mandatory

        Criteria to validate the field.

        • comparatorstring, mandatory

          Comparator of the criteria.

        • fieldJSON object, mandatory

          Field details of the criteria.

          • api_namestring, optional

            Specify the API name of the field.

          • idstring, mandatory

            Specify the ID of the field. Use the Fields Metadata API to retrieve this ID.

        • typestring, mandatory

          Type of the criteria to denote whether it is checked against a field value or another field.

        • valuestring, mandatory

          Value against which the field value should be checked.

      • validation_messagestring, mandatory

        Message to be displayed when validation fails.

    • sequenceinteger, mandatory

      Position in which the field should be displayed in the transition popup.

    • fieldJSON object, mandatory

      Details of the field configured in during transition.

      • api_namestring, optional

        Specify the API name of the field.

      • idstring, mandatory

        Specify the ID of the field. Use the Fields Metadata API to retrieve this ID.

    • optionalBoolean, optional

      Denotes whether the input is optional for the user during the transition.

    • typestring, mandatory

      Type of the configured input.
      Possible values: field, related_list, info, attachment, tags, notes, checklist, widget, kiosk.

  • api_namestring, mandatory

    Specify the API name of the transition.

  • namestring, mandatory

    Specify the name of the transition.

  • transition_typestring, mandatory

    Specify the type of transition relationship.
    Possible values: standalone_transition, parallel_transition, child_transition.

  • actionsJSON array, optional

    List of actions configured to be triggered after the transition is completed. These actions correspond to the automation that runs in the After Transition stage.

    • namestring, optional

      Specify the name of the action associated with the transition.

    • detailsJSON object, optional

      Specify the details of the configured action.

      • namestring, optional

        Specify the name of the action.

      • idstring, optional

        Specify the ID of the action. Retrieve this value using the corresponding action-specific Get API based on the selected action type.

    • idstring, optional

      Specify the ID of the action associated with the transition.

    • typestring, optional

      Specify the type of the action.

      Possible values: field_updates, add_tags, remove_tags, email_notifications, sms, whatsapp, tasks, create_record, add_meeting, schedule_call, convert, webhooks, functions.

  • color_codestring, optional

    Specify a visual color code associated with the transition for display or editor representation.

• statesJSON array, optional

  Specify the list of states associated with the blueprint. A state represents a stage or condition in the business process through which a record moves.

  • namestring, optional

    Specify the display name of the state.

  • api_namestring, mandatory

    Specify the API name of the state.

  • pick_list_valueJSON object, optional

    Specify the picklist option mapped with the state. In Zoho CRM, blueprint states are generally tied to the values of the selected process field.

    • idstring, mandatory

      Specify the ID of the picklist option. Use the Picklist Values API or the Fields Metadata API to retrieve this ID.

    • actual_valuestring, optional

      Specify the actual value of the mapped picklist option.

  • moduleJSON object, optional

    Specify the module details for which the state is configured.

    • api_namestring, optional

      Specify the API name of the module.

    • idstring, mandatory

      Specify the ID of the module. Use the Modules Metadata API to retrieve this ID.

  • state_escalationJSON object, optional

    Specify escalation alert configuration for the state. State escalation can trigger actions if a record remains in the state longer than the configured duration.

    • periodstring, mandatory

      Specify the time period type.
      Possible values: days, hours, minutes, business_days, business_hours.

    • valueinteger, mandatory

      Specify the numeric value of the defined period.

    • trigger_detailsJSON array, mandatory

      Specify trigger configurations for the state escalation.

      • periodstring, mandatory

        Specify the period type for the trigger.
        Possible values: days, hours, minutes.

      • execute_typestring, mandatory

        Specify when the trigger executes relative to the escalation point.
        Possible values: before, on, after.

      • valueinteger, mandatory

        Specify the time value for trigger execution.

      • actionsJSON array, optional

        Specify the list of actions configured for the trigger.

        • detailsJSON object, optional
          • escalate_toJSON array, optional
            • idstring, mandatory
            • typestring, mandatory

              Possible values: user, role, group, team_user, profile.

          • idstring, mandatory

            Specify the ID of the configured escalation action. Retrieve this value using the corresponding action-specific Get API based on the selected action type.

          • namestring, optional
        • idstring, optional
        • namestring, optional
        • typestring, optional

          Possible values: sla, email_notifications, tasks, field_updates, webhooks, functions, circuits, whatsapp, sms.

• layoutJSON object, mandatory

  Specify the details of the layout for which the blueprint is configured. Layout mapping ensures that the process applies within the intended record design and business context.

  Provide either id or api_name based on metadata availability. Use the Layouts Metadata API to retrieve valid layout identifiers.

  • api_namestring, optional

    Specify the API name of the layout.

  • namestring, optional

    Specify the name of the layout.

  • idstring, mandatory

    Specify the ID of the layout. Use the Layouts Metadata API to retrieve this ID.

• fieldJSON object, mandatory

  Specify the details of the field for which the blueprint is configured. This is the process field whose values are mapped to the states of the blueprint, such as Stage or Status.

  The selected field must be a Blueprint-supported process field (typically picklist/stage-like). Provide either id or api_name based on metadata availability. Use the Fields Metadata API to retrieve valid field identifiers.

  • api_namestring, optional

    Specify the API name of the field for which the blueprint is configured.

  • field_labelstring, optional

    Specify the label of the field for which the blueprint is configured.

  • idstring, mandatory

    Specify the ID of the field for which the blueprint is configured. Use the Fields Metadata API to retrieve this ID.

• api_namestring, optional

  Specify the API name of the blueprint.

• namestring, mandatory

  Specify the name of the blueprint. This is the human-readable label used to identify the process configuration in Zoho CRM.

• descriptionstring, optional

  Specify the description of the blueprint, including its business purpose, scope, or any important notes about how the process should be used.

• connectionsJSON array, optional

  Specify the logical connections between states mapped with transitions. These connections define how a transition moves a record from one source state to a target state.

  Each connection should reference a transition defined in the transitions array.

  • to_stateJSON object, mandatory

    Specify the target state associated with the connection.

    • namestring, optional

      Specify the name of the target state.

    • api_namestring, mandatory

      Specify the API name of the target state.

  • api_namestring, mandatory

    Specify the API name of the connection.

  • transitionsJSON object, mandatory

    Specify the transition associated with the connection.

    • api_namestring, mandatory

      Specify the API name of the transition.

    • namestring, optional

      Specify the name of the transition.

    • precedenceinteger, optional

      Specify the precedence of the transition where multiple transitions are associated with similar paths.

  • from_stateJSON object, mandatory

    Specify the source state associated with the connection.

    • namestring, optional

      Specify the name of the source state.

    • api_namestring, mandatory

      Specify the API name of the source state.