How to retrieve blueprint details in Zoho Desk

Blueprint details in Zoho Desk can be retrieved programmatically via a straightforward REST API call, giving you structured access to a specific blueprint's configuration and metadata by its unique identifier.

Why this matters

When building integrations, custom dashboards, or automation scripts around Zoho Desk's process automation features, you often need to inspect a blueprint's current state, stages, and transitions without navigating the UI. Retrieving blueprint details via the API lets your team validate configurations, audit workflows, or feed blueprint data into external systems. This is especially relevant for teams running complex support processes — such as multi-stage return and refund flows — where programmatic visibility is essential. ^[8]

---

Step-by-step

Step 1. Confirm you have API access to your Zoho Desk portal and that you hold a valid OAuth 2.0 access token with the appropriate Desk scopes. Without a valid token, all requests to the Zoho Desk REST API will be rejected. ^[6]

Step 2. Identify the blueprintId for the blueprint you want to inspect. This is the unique identifier assigned to the blueprint within your Zoho Desk portal. You can find it by listing blueprints through the API or by inspecting the URL when viewing a blueprint in the Zoho Desk admin panel. ^[7]

Step 3. Construct your HTTP request using the GET method against the following endpoint, substituting {blueprintId} with the actual identifier you collected in Step 2: ^[6]

GET /api/v1/blueprints/{blueprintId}

Step 4. Optionally, pass additional query parameters using the p dictionary if your integration requires filtering or pagination of the response payload. These are supplied as standard URL query parameters appended to the request. ^[7]

Step 5. Send the request. A successful call returns the blueprint's details — including its states, transitions, and any configured actions — as a structured response. In Python, the call looks like this: [^6, ^7]

def op_1_get_blueprint_details(self, blueprintId: str, p: dict = None):
    """Get Blueprint Details"""
    return self.c.request("GET", f"/api/v1/blueprints/{blueprintId}", p, None)

Step 6. Parse the response body to extract the blueprint metadata your integration needs. For example, you may want to read the defined stages to verify that mandatory widget actions — such as calendar scheduling, map inputs, or survey prompts — are correctly attached to the relevant transitions. ^[8]

---

Common pitfalls

• Incorrect blueprintId: Passing a malformed or non-existent blueprint ID will result in an error response. Always validate the ID against your portal before making the call. ^[6]

• Missing or expired OAuth token: Zoho Desk's API requires a current, valid access token. If your token has expired, refresh it before retrying the request. ^[7]

• State transition limits: Be aware that a single state transition in a blueprint supports up to 16 connections. If your blueprint configuration exceeds this, you may encounter unexpected behaviour when retrieving or acting on transition data. ^[1]

• Edition restrictions: Some blueprint capabilities — such as widget-based mandatory actions — are only available on the Professional and Enterprise editions of Zoho Desk. If your portal is on a lower tier, certain blueprint details may not appear in the response. ^[8]

---

What to check

• Verify the blueprintId is correct by cross-referencing it with the blueprint list in your Zoho Desk admin panel before making the API call.
• Confirm your OAuth token scope includes the necessary Zoho Desk permissions to read blueprint configurations.
• Review the returned transition data to ensure all expected states, actions, and widget integrations are present and match your intended process design. ^[8]

---

*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For platform-level issues, always raise a ticket directly with the Zoho Desk support team.*