How to get during transition form in Zoho Desk

Retrieving the "during transition" form for a Zoho Desk ticket lets you inspect exactly which fields are presented to an agent when they move a ticket through a specific workflow transition — a key step before automating or validating transition logic.

Why this matters

Zoho Desk workflow transitions can display custom forms mid-process, collecting additional data from agents before a status change is committed. If you are building an integration, auditing your support process, or troubleshooting why a transition behaves unexpectedly, you need to fetch this form definition programmatically. Understanding the form structure also helps you pre-populate or validate field values in automated flows. As always, Beam Help is independent expert support for Zoho — we are not official Zoho support.

Step-by-step

Step 1. Identify the two key identifiers you will need: the ticketId of the ticket you are working with, and the transitionId of the specific workflow transition you want to inspect. Both values are available from earlier API calls that list tickets and their available transitions. ^[1]

Step 2. Construct your request using the GET method against the following endpoint pattern, substituting your real values for the placeholders:

GET /api/v1/tickets/{ticketId}/transitions/{transitionId}/duringTransitionForm

Replace {ticketId} with the numeric or string ID of the target ticket, and {transitionId} with the ID of the transition whose mid-process form you want to retrieve. ^[1]

Step 3. Optionally, pass additional query parameters via the p argument if your integration requires filtering or pagination of the form fields returned. This maps to the p parameter accepted by the endpoint. ^[1]

Step 4. Send the authenticated request to the Zoho Desk API. A minimal Python example using a pre-configured client looks like this:

result = client.op_8_get_during_transition_form(
    ticketId="123456",
    transitionId="789",
    p=None  # pass a dict here if you need extra query params
)

The method issues a GET request to the constructed URL and returns the form definition as a response object. ^[1]

Step 5. Parse the response to extract the field definitions included in the during-transition form. These fields represent what an agent sees and must fill in before the transition completes. Use this data to drive validation logic, pre-fill values, or display the form in a custom interface. ^[1]

Common pitfalls

• Wrong transition ID for the ticket's current state. Not every transition is available for every ticket at all times. If you supply a transitionId that is not currently valid for the ticket's status, the API will return an error. Always confirm available transitions for a ticket before calling this endpoint. ^[1]

• Missing or expired OAuth token. The Zoho Desk API requires a valid OAuth 2.0 bearer token scoped to desk operations. An expired or incorrectly scoped token will result in a 401 or 403 response regardless of whether your IDs are correct. ^[1]

• Confusing ticketId with the ticket number. Zoho Desk distinguishes between the human-readable ticket number (e.g., #1042) and the internal ticketId used by the API. Always use the internal ID in the URL path. ^[1]

What to check

• Confirm both IDs are correct — verify that ticketId and transitionId exist and that the transition is currently available for that ticket's state before making the call. ^[1]
• Inspect the returned field list — ensure the form fields in the response match what you expect agents to see in the Zoho Desk UI for that transition. ^[1]
• Validate authentication scope — confirm your OAuth token includes the necessary Desk API permissions so the request is not rejected before it reaches the transition logic. ^[1]