Start workflow for a file/folder
This API starts a workflow on the selected file or folder.
Endpoints
OAuth Scope
WorkDrive.workflowinstances.CREATECopied!
curl --request POST \
--url https://www.zohoapis.com/workdrive/api/v1/files/{resource_id}/workflowinstances \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'content-type: application/vnd.api+json' \
--data '{"data":{"attributes":{"workflow_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003010","during_action_info":[{"action_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003055","details":{"custom_meta_details":{"data_template_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003011","custom_data":[{"custom_field_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE1","value":["reyansh.ahuja@zylker.com"]},{"custom_field_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE2","value":"Kindly review this file."},{"custom_field_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE3","value":1765521000000}]}}}]},"type":"workflowinstances"}}'Path Parameters
resource_idstring(Required)
The unique ID of the file or folder.
Request Body
application/vnd.api+jsondataJSON Object(Required)
Hide Sub-Attributes
attributesJSON Object(Required)
Hide Sub-Attributes
workflow_idstring(Required)
The ID of the workflow to initiate on the selected resource.
during_action_infoJSON Array(Optional)
If a During Action is configured for the transition (such as comments, feedback, or any other fields), you must include those values in this parameter as shown in the payload. Use the Get During Actions for an Instance Transition API to retrieve the configured During Actions and construct the required payload.
How to get the transition ID's for instances:
Start transition ID will be available as one of the parameter in included attribute of Get Workflow instance API response.
Refer to this table for the value formats supported by each custom metadata field type.
Note:
If a field is marked Mandatory in the workflow configuration, a non-empty value must be provided here.
Show Sub-Attributes
action_idstring(Optional)
The ID of the configured During Action. Provide this for each entry in during_action_info. Use the Get Actions for a Transition API and copy the action ID from its response.
detailsJSON Object(Optional)
The details payload for this action_id entry in during_action_info. Build this object from the Get Actions for a Transition API response, include only the fields configured for that action (for example, custom_meta_details), and provide non-empty values for mandatory fields.
Show Sub-Attributes
custom_meta_detailsJSON Object(Optional)
Custom metadata values for this action. Build this object from the Get Actions for a Transition API response and include data_template_id and custom_data for the configured fields only. For each custom_data item, pass custom_field_id and value in the expected format for that field type. If a field is marked Mandatory in workflow configuration, you must provide a non-empty value.
Show Sub-Attributes
data_template_idstring(Optional)
The ID of the data template configured in this action. Get this from the Get Actions for a Transition API response under custom_meta_details.
custom_dataJSON Array(Optional)
The list of field values for this data_template_id. Include only configured fields from the Get Actions for a Transition API response. Each item must include custom_field_id and value in the expected format for that field type. If a field is marked Mandatory in workflow configuration, you must provide a non-empty value.
Show Sub-Attributes
custom_field_idstring(Optional)
The ID of the configured custom field in custom_meta_details.custom_data. Get this from the Get Actions for a Transition API response.
valuestring(Optional)
The value for this custom_field_id. Provide the value in the expected format for that field type (for example: string, number, boolean, epoch milliseconds for date or datetime, single choice, or array for multi-value fields). If the field is marked Mandatory in workflow configuration, you must provide a non-empty value.
typestring(Required)
The JSON:API resource type. Always "workflowinstances".
Allowed Values :
Show Values ▾
workflowinstancesCopied!
Copy all as JSON Array
{
"data": {
"attributes": {
"workflow_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003010",
"during_action_info": [
{
"action_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003055",
"details": {
"custom_meta_details": {
"data_template_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003011",
"custom_data": [
{
"custom_field_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE1",
"value": [
"reyansh.ahuja@zylker.com"
]
},
{
"custom_field_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE2",
"value": "Kindly review this file."
},
{
"custom_field_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE3",
"value": 1765521000000
}
]
}
}
}
]
},
"type": "workflowinstances"
}
}
{
"transitionusers": [
{
"instanceId": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"userTypeStr": "string",
"transitionId": "string",
"userAvatarUrl": "string",
"id": "string",
"userName": "string",
"userId": "string",
"status": 0
}
],
"resourceId": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"resourceIconClass": "string",
"customMetaData": {
"data_template_id": "string",
"capabilities": {
"canMove": true,
"canEditComment": true,
"canShowActiveWorkflowInstance": true,
"canTrash": true,
"canCheckout": true,
"canFavourite": true,
"canCreateGroup": true,
"canDelete": true,
"canTrashFiles": true,
"canShowAccessStats": true,
"canLeave": true,
"canFavorite": true,
"canShare": true,
"canRestore": true,
"canHaveOrgTemplates": true,
"canDeleteComment": true,
"canRemoveShare": true,
"canCheckin": true,
"canCreateFiles": true,
"canUploadFiles": true,
"canAssociateDataTemplate": true,
"canCustomize": true,
"canCreateTask": true,
"canConfigureWorkflow": true,
"canAccessMyfolder": true,
"canEmailattach": true,
"canDiscardCheckout": true,
"canRead": true,
"canReadComment": true,
"canEdit": true,
"canRename": true,
"canZip": true,
"hasAppPermissionAlone": true,
"canSnooze": true,
"canReplytoComment": true,
"canSync": true,
"canShareFiles": true,
"canCancelCheckout": true,
"canMarkAsFinal": true,
"canMandateDataTemplate": true,
"canCreateComment": true,
"canCopy": true,
"canPublish": true,
"canDownload": true,
"canJoin": true,
"canDelistFile": true,
"canPartialRead": true,
"canShareSupport": true,
"canShowActivity": true,
"canLabel": true,
"canDiassociate": true,
"canShowWorkflowBlueprint": true,
"canAbortWorkflow": true,
"canResolveComment": true,
"canManage": true,
"canAddMembers": true,
"canOpenWithAddons": true
},
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"can_add_or_update": true,
"custommetadata_id": "string",
"name": "string",
"resource_id": "string",
"description": "string",
"dataTemplateType": 0,
"custom_data": [
{
"data_template_id": "string",
"apiName": "string",
"cursorLink": {
"cursor": {}
},
"reorder_choices": [
{}
],
"custom_field_id": "string",
"column_name": "string",
"index": 0,
"display_name": "string",
"type": "string",
"field_properties": {
"min_value": "string",
"max_char_length": "string",
"allowedDate": {},
"description": "string",
"is_mandatory": true,
"default_value": "string",
"isSearchable": true,
"max_value": "string"
},
"multiEmailAdditionalInfo": [
{}
],
"isSearchableFieldUpdateInProgress": true,
"options": [
"string"
],
"emailAdditionalInfo": {
"avatarUrl": "string",
"displayName": "string",
"emailId": "string",
"userId": "string"
},
"choices": [
{}
],
"value": "string"
}
],
"status": true,
"is_associated_without_cf": true
},
"resourceName": "string",
"workflowactions": [
{
"actionType": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {
"resourceDetails": {
"resourceId": "string",
"name": "string",
"parentIdRef": "string",
"parentId": "string",
"resourceIdRef": "string"
},
"notificationDetails": {
"subject": "string",
"recipients": [
null
],
"notifyVia": {},
"message": "string"
},
"customFunctionExtraDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
null
],
"functionMapId": 0
},
"shareDetails": {
"resourceId": "string",
"shareCollaborators": [
null
],
"resourceIdRef": "string"
},
"defaultDeadlineNotificationDetails": {
"recipients": [
null
]
},
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
null
],
"functionMapId": 0
},
"customMetaDetails": {
"resourceId": "string",
"isDeleted": true,
"dataTemplateId": "string",
"name": "string",
"customData": [
null
],
"isAssociatedWithoutCf": true,
"resourceIdRef": "string"
},
"taskDetails": {
"assignerMessage": "string",
"taskType": 0,
"dueAfter": 0,
"roleId": 0,
"taskCollaboratorsRef": "string",
"title": "string",
"taskCollaborators": [
null
],
"customFieldsToCollect": [
null
],
"completionRule": 0
}
},
"category": 0
}
],
"journeyId": {},
"initiatedTimeInMillis": 0,
"transitions": [
{
"workflow_id": "string",
"workflowInstanceInfo": {},
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"canPerformTransition": true,
"transitionId": "string",
"module": "string",
"description": "string",
"workflowactions": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"triggers": [
{
"trigger_id_str": "string",
"cursorLink": {},
"criteria": {
"value": {},
"group": []
},
"trigger_type": "string",
"trigger_id": "string",
"details": {}
}
],
"completionRule": 0,
"duringActionInfo": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"target_state_id": "string",
"isUserPartOfTransition": true,
"transitionperformers": [
{
"performerUserTypeStr": "string",
"cursorLink": {},
"transitionId": "string",
"performerName": "string",
"emailId": "string",
"performerAvatarUrl": "string",
"id": "string",
"performerId": "string",
"performerType": "string"
}
],
"source_state_id": "string",
"name": "string",
"transition_id_str": "string",
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
{}
],
"functionMapId": 0
},
"action": [
{
"cursorLink": {},
"action_type": "string",
"action_id": "string",
"module": "string",
"action_id_str": "string",
"details": {},
"category": 0
}
],
"id": "string"
}
],
"instanceStatus": 0,
"currentStateInfo": {
"workflow_id": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"module": "string",
"name": "string",
"waitForEveryone": 0,
"description": "string",
"action": [
{
"cursorLink": {
"cursor": {}
},
"action_type": "string",
"action_id": "string",
"module": "string",
"action_id_str": "string",
"details": {
"resourceDetails": {},
"notificationDetails": {
"recipients": []
},
"customFunctionExtraDetails": {
"arguments": []
},
"shareDetails": {
"shareCollaborators": []
},
"defaultDeadlineNotificationDetails": {
"recipients": []
},
"customFunctionDetails": {
"arguments": []
},
"customMetaDetails": {
"customData": []
},
"taskDetails": {
"taskCollaborators": [],
"customFieldsToCollect": []
}
},
"category": 0
}
],
"workflowactions": [
{
"actionType": "string",
"cursorLink": {
"cursor": {}
},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {
"resourceDetails": {},
"notificationDetails": {
"recipients": []
},
"customFunctionExtraDetails": {
"arguments": []
},
"shareDetails": {
"shareCollaborators": []
},
"defaultDeadlineNotificationDetails": {
"recipients": []
},
"customFunctionDetails": {
"arguments": []
},
"customMetaDetails": {
"customData": []
},
"taskDetails": {
"taskCollaborators": [],
"customFieldsToCollect": []
}
},
"category": 0
}
],
"state_id": "string",
"deadline": {
"period": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"schedules": [
{
"period": "string",
"cursorLink": {},
"workflowactions": [
null
],
"id": "string",
"type": "string",
"value": 0,
"actions": [
null
],
"actionsToCreate": [
null
]
}
],
"customFieldId": "string",
"id": "string",
"value": 0,
"schedulesToCreate": [
{
"period": "string",
"cursorLink": {},
"workflowactions": [
null
],
"id": "string",
"type": "string",
"value": 0,
"actions": [
null
],
"actionsToCreate": [
null
]
}
]
},
"state_id_str": "string"
},
"duringActionInfo": [
{
"actionType": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {
"resourceDetails": {
"resourceId": "string",
"name": "string",
"parentIdRef": "string",
"parentId": "string",
"resourceIdRef": "string"
},
"notificationDetails": {
"subject": "string",
"recipients": [
null
],
"notifyVia": {},
"message": "string"
},
"customFunctionExtraDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
null
],
"functionMapId": 0
},
"shareDetails": {
"resourceId": "string",
"shareCollaborators": [
null
],
"resourceIdRef": "string"
},
"defaultDeadlineNotificationDetails": {
"recipients": [
null
]
},
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
null
],
"functionMapId": 0
},
"customMetaDetails": {
"resourceId": "string",
"isDeleted": true,
"dataTemplateId": "string",
"name": "string",
"customData": [
null
],
"isAssociatedWithoutCf": true,
"resourceIdRef": "string"
},
"taskDetails": {
"assignerMessage": "string",
"taskType": 0,
"dueAfter": 0,
"roleId": 0,
"taskCollaboratorsRef": "string",
"title": "string",
"taskCollaborators": [
null
],
"customFieldsToCollect": [
null
],
"completionRule": 0
}
},
"category": 0
}
],
"initiatedByUser": "string",
"initiatedByAvatarUrl": "string",
"statusChangedTime": "string",
"workflowInfo": {
"modifiedTime": "string",
"workflow_id": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"createdByZuid": "string",
"createdByUser": "string",
"dataTemplateId": "string",
"groupId": "string",
"modifiedByZuid": "string",
"description": "string",
"transitions": [
{
"workflow_id": "string",
"workflowInstanceInfo": {},
"cursorLink": {
"cursor": {}
},
"canPerformTransition": true,
"transitionId": "string",
"module": "string",
"description": "string",
"workflowactions": [
{}
],
"triggers": [
{}
],
"completionRule": 0,
"duringActionInfo": [
{}
],
"target_state_id": "string",
"isUserPartOfTransition": true,
"transitionperformers": [
{}
],
"source_state_id": "string",
"name": "string",
"transition_id_str": "string",
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
null
],
"functionMapId": 0
},
"action": [
{}
],
"id": "string"
}
],
"states": [
{
"workflow_id": "string",
"cursorLink": {
"cursor": {}
},
"module": "string",
"name": "string",
"waitForEveryone": 0,
"description": "string",
"action": [
{}
],
"workflowactions": [
{}
],
"state_id": "string",
"deadline": {
"period": "string",
"cursorLink": {},
"schedules": [
null
],
"customFieldId": "string",
"id": "string",
"value": 0,
"schedulesToCreate": [
null
]
},
"state_id_str": "string"
}
],
"chartData": {
"nodes": [
{
"anchorPoints": [
{}
],
"id": "string",
"position": {}
}
],
"connections": [
{
"id": "string",
"source": {},
"target": {}
}
]
},
"sourceWorkflowId": 0,
"workflowinstances": [
{}
],
"modifiedByUser": "string",
"createdTime": "string",
"createdTimeInMillis": 0,
"sequenceNumber": 0,
"currentRecordCount": 0,
"module": "string",
"startTransition": {
"workflow_id": "string",
"workflowInstanceInfo": {},
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"canPerformTransition": true,
"transitionId": "string",
"module": "string",
"description": "string",
"workflowactions": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"triggers": [
{
"trigger_id_str": "string",
"cursorLink": {},
"criteria": {
"value": {},
"group": []
},
"trigger_type": "string",
"trigger_id": "string",
"details": {}
}
],
"completionRule": 0,
"duringActionInfo": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"target_state_id": "string",
"isUserPartOfTransition": true,
"transitionperformers": [
{
"performerUserTypeStr": "string",
"cursorLink": {},
"transitionId": "string",
"performerName": "string",
"emailId": "string",
"performerAvatarUrl": "string",
"id": "string",
"performerId": "string",
"performerType": "string"
}
],
"source_state_id": "string",
"name": "string",
"transition_id_str": "string",
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
{}
],
"functionMapId": 0
},
"action": [
{
"cursorLink": {},
"action_type": "string",
"action_id": "string",
"module": "string",
"action_id_str": "string",
"details": {},
"category": 0
}
],
"id": "string"
},
"workflowactions": [
{
"actionType": "string",
"cursorLink": {
"cursor": {}
},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {
"resourceDetails": {},
"notificationDetails": {
"recipients": []
},
"customFunctionExtraDetails": {
"arguments": []
},
"shareDetails": {
"shareCollaborators": []
},
"defaultDeadlineNotificationDetails": {
"recipients": []
},
"customFunctionDetails": {
"arguments": []
},
"customMetaDetails": {
"customData": []
},
"taskDetails": {
"taskCollaborators": [],
"customFieldsToCollect": []
}
},
"category": 0
}
],
"initiationType": 0,
"creationType": 0,
"name": "string",
"clone": {},
"modifiedTimeInMillis": 0,
"status": 0
},
"instancelogs": [
{
"executedBy": "string",
"owner": "string",
"performedTransitionEvents": [
{
"country": "string",
"cursorLink": {},
"os": "string",
"action_type": 0,
"ip_address": "string",
"eventByUserEmailId": "string",
"event_by_user_type": 0,
"audit_info": [
null
],
"event_by": "string",
"event_by_user": "string",
"avatar_url": "string",
"action_id": 0,
"browser": "string",
"time": 0,
"resource_name": "string",
"device": "string",
"operation": "string",
"user_agent": "string",
"events": [
null
],
"accessTime": "string",
"info": "string",
"access_time": "string"
}
],
"triggerEventInfo": "string",
"executedTransitionId": {},
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"executedTime": "string",
"fromStateId": {},
"executedTransitionModule": "string",
"executedByAvatarUrl": "string",
"fromStateName": "string",
"executedTriggerId": {},
"executedByUser": "string",
"versionNumber": "string",
"performedActionEvents": [
{
"country": "string",
"cursorLink": {},
"os": "string",
"action_type": 0,
"ip_address": "string",
"eventByUserEmailId": "string",
"event_by_user_type": 0,
"audit_info": [
null
],
"event_by": "string",
"event_by_user": "string",
"avatar_url": "string",
"action_id": 0,
"browser": "string",
"time": 0,
"resource_name": "string",
"device": "string",
"operation": "string",
"user_agent": "string",
"events": [
null
],
"accessTime": "string",
"info": "string",
"access_time": "string"
}
],
"toStateName": "string",
"executedByUserType": 0,
"toStateId": {},
"executedTriggerType": "string",
"id": "string",
"executedTimeInMillis": 0,
"executedTransitionName": "string"
}
],
"statusChangedTimeInMillis": 0,
"initiatedTime": "string",
"customFunctionDetails": {
"functionId": "string",
"functionName": "string",
"arguments": [
{
"dataType": "string",
"name": "string",
"value": "string"
}
],
"functionMapId": 0
},
"id": "string",
"workflowId": "string",
"initiatedBy": "string"
}
{
"errors": [
{
"id": "AT042",
"title": "Workflow feature is not enabled by the admin for this org"
}
]
}
{
"errors": [
{
"id": "AT046",
"title": "Invalid manual start workflowId"
}
]
}
{
"errors": [
{
"id": "R008",
"title": "Unauthorized access"
}
]
}
{
"errors": [
{
"id": "AT020",
"title": "Invalid during action"
}
]
}
{
"errors": [
{
"id": "AT032",
"title": "Max workflow instances count for the day reached"
}
]
}
{
"errors": [
{
"id": "F000",
"title": "General Exception"
}
]
}
{
"errors": [
{
"id": "AT026",
"title": "Workflow is not active"
}
]
}
{
"errors": [
{
"id": "AT037",
"title": "Unable to start workflow for locked resource"
}
]
}
{
"errors": [
{
"id": "AT007",
"title": "This resource already running in this/some other workflow"
}
]
}
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.