Create Automation Task

Purpose

To create an automation task in your Zoho CRM organization.

Endpoints

POST /settings/automation/tasks

Request Details

Request URL

To create an automation tasks:
{api-domain}/crm/{version}/settings/automation/tasks

Supported modules

Leads, Accounts, Contacts, Deals, Tasks, Meetings, Calls, Products, Quotes, Sales Orders, Purchase Orders, Invoices, Campaigns, Vendors, Price Books, Cases, and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.automation_actions.{operation_type}

Possible operation types

ALL - Full access to tasks
CREATE - Create tasks

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/tasks"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X POST
-d "@createtasks.json"

Input JSON

namestring, mandatory
Specify the display name of the task
field_mappingsJSON array, mandatory
When an automation task is created the fields should be mapped to tasks modules. Use this JSON array to map the fields of Automation Tasks fields to create tasks automatically when an automation is triggered.
- fieldJSON object, mandatory
  - api_namestring, mandatory
    Specify the API name of the field present in the Tasks module.
  - idstring, mandatory
    Specify the ID of the field present in the Tasks module.
- typestring
  The type of value for the task field.
  Possible values:
  static - Specify type as static when the value is fixed for the value key
  merge_field - Specify type as merge_field when the dynamic value generated from value of the fields of the module for which the task is created, is assigned to the value key.
  execution_time - Specify type as date or datetime when the value key gets its value based on time .
- Value denotes the value of the Tasks fields. The value is different for each specified type. Format depends on the type field:
  - When type is static:
    When type is static value can take either of the below two formats:
    valuestring, mandatory when type is static
    For string or number value.
    For example: "value": "Not Started"
    "value": "1234"
    OR
    valuestring array, mandatory when type is static
    For multi-select fields.
    For example: "value": ["Option 1", "Option 2"] "
  - When type is merge_field:
    - valuestring, mandatory when type is merge_field
      Merge field placeholder referencing CRM data from the module for which the Task is created. A field can take the value of the merge field that is same data type as the field. To merge any field from a module, it should be specified in this format ${!module_api_name.field_api_name}. Example: ${!users.website} for URL.
  - When type is execution_time:
    Use when the value is computed at runtime for a date or datetime fields. For date or datetime fields only possible type is execution_time. In this case the value JSON object the keys are:
    - periodstring, mandatory when type is execution_time
      Unit for calculating offset.
      Possible value: days.
    - unitstring, mandatory when type is execution_time
      Number of units to add/subtract.
      Example: "period": "4".
    - signstring, mandatory when type is execution_time
      Specify whether to add or subtract "unit" "period" from trigger field.
      Possible values: plus, minus
      Example: "sign": "plus".
    - trigger_fieldstring, mandatory when type is execution_time
      Specify the merge field or system value that acts as the base date.
      Example: ${CURRENTTIME} or ${!Tasks.Due_Date}.
    - timestring, mandatory when type is execution_time and for date-time fields
      Specify the time of day in 24-hour format.
      Example: "12:00". Applicable only for datetime fields
    - notify_typestring, mandatory when type is execution_time
      Specify the type of notification.
      Possible values: "popup","email","emailandpopup".
display_valuestring
Consists of a description of the value.

feature_typestring
Specify the feature type of the task.
Possible values: workflow, assignmentrules, connectedworkflow. The default value is workflow.
notifyBoolean
Specify whether the task owner will be notified via email about the task
associatedBoolean
Specify whether the task is linked to an automation.

Sample Request

Copied{
    "tasks": [
        {
            "module": {
                "api_name": "Tasks",
                "id": "6660682000000002193"
            },
            "related_module": null,
            "notify": true,
            "field_mappings": [
                {
                    "field": {
                        "api_name": "Remind_At",
                        "id": "6660682000000025017"
                    },
                    "type": "execution_time",
                    "value": {
                        "notify_type": "emailandpopup",
                        "period": "days",
                        "unit": "0",
                        "trigger_field": "${!Tasks.Due_Date}",
                        "sign": "plus",
                        "time": "00:00"
                    }
                },
                {
                    "field": {
                        "api_name": "Description",
                        "id": "6660682000000002291"
                    },
                    "type": "merge_field",
                    "value": "Automated task for ${!Leads.First_Name}${!Leads.Last_Name}"
                },
                {
                    "field": {
                        "api_name": "Subject",
                        "id": "6660682000000002271"
                    },
                    "type": "static",
                    "value": "SampleTask"
                },
                {
                    "field": {
                        "api_name": "Due_Date",
                        "id": "6660682000000002273"
                    },
                    "type": "execution_time",
                    "value": {
                        "period": "days",
                        "unit": "12",
                        "trigger_field": "${CURRENTTIME}",
                        "sign": "plus"
                    }
                },
                {
                    "field": {
                        "api_name": "Status",
                        "id": "6660682000000002279"
                    },
                    "type": "static",
                    "value": "Not Started"
                },
                {
                    "field": {
                        "api_name": "Priority",
                        "id": "6660682000000002281"
                    },
                    "type": "static",
                    "value": "High"
                },
                {
                    "field": {
                        "api_name": "URL_1",
                        "id": "6660682000001522480"
                    },
                    "type": "merge_field",
                    "value": "${!Leads.Website}"
                },
                {
                    "field": {
                        "api_name": "Number_1",
                        "id": "6660682000001522575"
                    },
                    "type": "merge_field",
                    "value": "${!Leads.No_of_Employees}"
                },
                {
                    "display_value": "100000000000000000",
                    "field": {
                        "api_name": "Long_Integer_1",
                        "id": "6660682000001522533"
                    },
                    "type": "static",
                    "value": "100000000000000000"
                },
                {
                    "field": {
                        "api_name": "Owner",
                        "id": "6660682000000002269"
                    },
                    "type": "static",
                    "value": {
                        "name": "John Smith",
                        "id": "6660682000001180618"
                    }
                },
                {
                    "field": {
                        "api_name": "Date_Time_1",
                        "id": "6660682000001522631"
                    },
                    "type": "execution_time",
                    "value": {
                        "period": "days",
                        "unit": "1",
                        "trigger_field": "${CURRENTTIME}",
                        "sign": "plus",
                        "time": "00:00"
                    }
                },
                {
                    "field": {
                        "api_name": "Multi_Select_1",
                        "id": "6660682000001522499"
                    },
                    "type": "static",
                    "value": [
                        "Option 1",
                        "Option 2"
                    ]
                },
                {
                    "field": {
                        "api_name": "Single_Line_1",
                        "id": "6660682000001522561"
                    },
                    "type": "static",
                    "value": "sample task"
                },
                {
                    "field": {
                        "api_name": "Pick_List_1",
                        "id": "6660682000000922691"
                    },
                    "type": "static",
                    "value": "Voter ID"
                },
                {
                    "field": {
                        "api_name": "Email_1",
                        "id": "6660682000001465098"
                    },
                    "type": "static",
                    "value": "john@zohotest.cim"
                },
                {
                    "field": {
                        "api_name": "Date_1",
                        "id": "6660682000001522519"
                    },
                    "type": "execution_time",
                    "value": {
                        "period": "days",
                        "unit": "1",
                        "trigger_field": "${CURRENTTIME}",
                        "sign": "plus"
                    }
                },
                {
                    "field": {
                        "api_name": "Percent_1",
                        "id": "6660682000001522617"
                    },
                    "type": "static",
                    "value": "50"
                },
                {
                    "field": {
                        "api_name": "Currency_1",
                        "id": "6660682000001522589"
                    },
                    "type": "merge_field",
                    "value": "${!Leads.Annual_Revenue}"
                },
                {
                    "field": {
                        "api_name": "Phone_1",
                        "id": "6660682000001522603"
                    },
                    "type": "merge_field",
                    "value": "${!Leads.Phone}"
                },
                {
                    "field": {
                        "api_name": "Decimal_1",
                        "id": "6660682000001522547"
                    },
                    "type": "static",
                    "value": "12"
                }
            ],
            "name": "NewTask"
        }
    ]
}

Possible Errors

REQUIRED_DATA_NOT_FOUNDHTTP 400
Required field not found
Resolution: This error occurs if required fields are not provided in the INPUT Json.
EXPECTED_FIELD_MISSINGHTTP 400
Specify at least one field.
Resolution: This error occurs if api_name or id of field is not provided in field_mappings.
AMBIGUITY_DURING_PROCESSINGHTTP 400
Ambiguity while processing the request.

Resolution: The field's unique ID and API name seem to be mismatched. Please specify the correct field ID along with its corresponding API name. Use the GET Fields Metadata API to retrieve the API names and IDs of your modules.
INVALID_DATAHTTP 400
Unsupported merge field provided.
Resolution: This error occurs when merge field is not proper. Provide a valid merge field.
INVALID_DATAHTTP 400
Please specify valid due date
Resolution: Specify a value due date.
INVALID_DATAHTTP 400
The id given seems to be invalid
Resolution: Provide valid ID.
MANDATORY_NOT_FOUNDHTTP 400
Mandatory field is not given
Resolution: Provide all mandatory fields in the input JSON.
DEPENDENT_FIELD_MISSINGHTTP 400
Dependent field missing
Resolution: This issue occurs if a dependent field in value JSON object is not provided.
NO_PERMISSIONHTTP 401
Permission denied
Resolution: The user does not have manage workflow permission.

DEPENDENT_MISMATCHHTTP 401

The given value is invalid
Resolution: This error occurs if length of the field provided is more than the allowed length. Provided value in valid length.

OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to add automation tasks. Create a new token with valid scope. Refer to the Scope section for details.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to Request URL section for details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Response JSON

Copied{
    "tasks": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "6660682000001550002"
            },
            "message": "task created successfully",
            "status": "success"
        }
    ]
}