Perform Transition for a Workflow Instance
This API executes a specified transition on an existing workflow instance.
Use this when you want to move the instance from its current state to the next state whenever the transition condition is met. If the transition requires During inputs (feedback, approver emails, form fields), provide them in during_action_info.
Endpoints
OAuth Scope
WorkDrive.workflowinstances.UPDATECopied!
curl --request POST \
--url https://www.zohoapis.com/workdrive/api/v1/workflowinstances/{instance_id}/transitions \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'content-type: application/vnd.api+json' \
--data '{"data":{"attributes":{"during_action_info":[{"action_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003098","details":{"custom_meta_details":{"data_template_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003011","custom_data":[{"custom_field_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE5","value":"Need some improvement."}]}}}],"transition_id":"sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003092"},"type":"transitions"}}'Path Parameters
instance_idstring(Required)
The unique ID of the workflow instance on which the transition will be performed.
Retrieve this ID using the active_workflow_instance parameter from the Files API response or from the Get Workflow Instances for a file/folder API by applying the in_progress instances filter for the resource.
Request Body
application/vnd.api+jsondataJSON Object(Required)
Hide Sub-Attributes
attributesJSON Object(Required)
Hide Sub-Attributes
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:
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.
transition_idstring(Required)
The ID of the transition to execute.
typestring(Required)
The JSON:API resource type. Always "transitions".
Allowed Values :
Show Values ▾
transitionsCopied!
Copy all as JSON Array
{
"data": {
"attributes": {
"during_action_info": [
{
"action_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003098",
"details": {
"custom_meta_details": {
"data_template_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003011",
"custom_data": [
{
"custom_field_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-NzMyMTM4NjAwMDAwMDAwMzAxMS03MzIxMzg2MDAwMDAwMDAzMDE5",
"value": "Need some improvement."
}
]
}
}
}
],
"transition_id": "sfftb8bae590ea97a4c8ba521f751b64452ca-7321386000000003092"
},
"type": "transitions"
}
}
{
"workflow_id": "string",
"workflowInstanceInfo": {
"transitionusers": [
{
"instanceId": "string",
"cursorLink": {
"cursor": {}
},
"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": {},
"reorder_choices": [
null
],
"custom_field_id": "string",
"column_name": "string",
"index": 0,
"display_name": "string",
"type": "string",
"field_properties": {},
"multiEmailAdditionalInfo": [
null
],
"isSearchableFieldUpdateInProgress": true,
"options": [
null
],
"emailAdditionalInfo": {},
"choices": [
null
],
"value": "string"
}
],
"status": true,
"is_associated_without_cf": true
},
"resourceName": "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
}
],
"journeyId": {},
"initiatedTimeInMillis": 0,
"transitions": [
{}
],
"instanceStatus": 0,
"currentStateInfo": {
"workflow_id": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"module": "string",
"name": "string",
"waitForEveryone": 0,
"description": "string",
"action": [
{
"cursorLink": {},
"action_type": "string",
"action_id": "string",
"module": "string",
"action_id_str": "string",
"details": {},
"category": 0
}
],
"workflowactions": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"state_id": "string",
"deadline": {
"period": "string",
"cursorLink": {
"cursor": {}
},
"schedules": [
{
"workflowactions": [],
"actions": [],
"actionsToCreate": []
}
],
"customFieldId": "string",
"id": "string",
"value": 0,
"schedulesToCreate": [
{
"workflowactions": [],
"actions": [],
"actionsToCreate": []
}
]
},
"state_id_str": "string"
},
"duringActionInfo": [
{
"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
}
],
"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": [
{}
],
"states": [
{
"workflow_id": "string",
"cursorLink": {},
"module": "string",
"name": "string",
"waitForEveryone": 0,
"description": "string",
"action": [
null
],
"workflowactions": [
null
],
"state_id": "string",
"deadline": {
"schedules": [],
"schedulesToCreate": []
},
"state_id_str": "string"
}
],
"chartData": {
"nodes": [
{
"anchorPoints": []
}
],
"connections": [
{}
]
},
"sourceWorkflowId": 0,
"workflowinstances": [
{}
],
"modifiedByUser": "string",
"createdTime": "string",
"createdTimeInMillis": 0,
"sequenceNumber": 0,
"currentRecordCount": 0,
"module": "string",
"startTransition": {},
"workflowactions": [
{
"actionType": "string",
"cursorLink": {},
"action_id": "string",
"module": "string",
"actionIdStr": "string",
"details": {},
"category": 0
}
],
"initiationType": 0,
"creationType": 0,
"name": "string",
"clone": {},
"modifiedTimeInMillis": 0,
"status": 0
},
"instancelogs": [
{
"executedBy": "string",
"owner": "string",
"performedTransitionEvents": [
{
"audit_info": [],
"events": []
}
],
"triggerEventInfo": "string",
"executedTransitionId": {},
"cursorLink": {
"cursor": {}
},
"executedTime": "string",
"fromStateId": {},
"executedTransitionModule": "string",
"executedByAvatarUrl": "string",
"fromStateName": "string",
"executedTriggerId": {},
"executedByUser": "string",
"versionNumber": "string",
"performedActionEvents": [
{
"audit_info": [],
"events": []
}
],
"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"
},
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"canPerformTransition": true,
"transitionId": "string",
"module": "string",
"description": "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
}
],
"triggers": [
{
"trigger_id_str": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"criteria": {
"comparator": "EQ",
"group_operator": "AND",
"value": {},
"key": "string",
"group": [
{}
]
},
"trigger_type": "string",
"trigger_id": "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
}
}
}
],
"completionRule": 0,
"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
}
],
"target_state_id": "string",
"isUserPartOfTransition": true,
"transitionperformers": [
{
"performerUserTypeStr": "string",
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"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": [
{
"dataType": "string",
"name": "string",
"value": "string"
}
],
"functionMapId": 0
},
"action": [
{
"cursorLink": {
"cursor": {
"next": "string",
"hasNext": true
}
},
"action_type": "string",
"action_id": "string",
"module": "string",
"action_id_str": "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
}
],
"id": "string"
}
{
"errors": [
{
"id": "R008",
"title": "Unauthorized access"
}
]
}
{
"errors": [
{
"id": "AT020",
"title": "Invalid during action"
}
]
}
{
"errors": [
{
"id": "AT024",
"title": "Invalid manual transitionId"
}
]
}
{
"errors": [
{
"id": "AT022",
"title": "User already performed transition for current execution"
}
]
}
{
"errors": [
{
"id": "F000",
"title": "General Exception"
}
]
}
{
"errors": [
{
"id": "AT018",
"title": "Transition source state id not matched with instance current state id"
}
]
}
{
"errors": [
{
"id": "AT019",
"title": "User not part of transition"
}
]
}
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.