How to remove pins in Zoho Desk

Removing pins in Zoho Desk can be accomplished via the dedicated pin-removal API endpoint, giving administrators a programmatic way to clean up pinned items within their helpdesk instance.

Why this matters

Pinned items in Zoho Desk help agents surface important tickets or records quickly, but stale pins can clutter the interface and slow down workflows. Knowing how to remove them — especially through the API — is essential for teams managing Zoho Desk at scale or building automation around their support operations. This is particularly relevant if you are integrating Zoho Desk with a custom backend or an AI copilot tool that manages helpdesk state programmatically.

Step-by-step

Step 1. Ensure your Zoho Desk OAuth connection is active and that your application holds a valid access token. The token must cover the appropriate Desk scopes — at minimum Desk.tickets.ALL or the relevant read/write scopes for the resource type you are unpinning. ^[1]

Step 2. If your access token has expired, trigger a token refresh before making any calls. Your backend should retrieve the stored refreshtoken, call the Zoho OAuth refresh endpoint, and persist the new accesstoken and its expiry timestamp back to your data store. ^[4]

Step 3. Confirm that your Zoho Desk client is initialised with the correct orgid. Without a valid organisation ID, requests to the Desk API will be rejected. If the orgid is not already stored, make a preliminary call to the organisations endpoint to discover and persist it before proceeding. ^[4]

Step 4. Call the pin-removal endpoint using an HTTP GET request to the path /api/v1/doc/_pinremoval. Pass any required query parameters via the p dictionary argument. In Python, this looks like: ^[2]

def get_pin_removal(self, p: dict = None):
    return self.c.request("GET", "/api/v1/_doc/___pin_removal", p, None)

Step 5. Inspect the response from the endpoint. A successful call will confirm that the pin has been removed. If the response contains an error code, check that your scopes, org_id, and access token are all valid before retrying. ^[2]

Step 6. If you are running automated tests against this operation, use a dedicated sandbox organisation to avoid accidentally modifying production data. The Zoho Desk test runner categorises operations by risk level, so mark pin-removal tests appropriately before executing them in bulk. ^[8]

Common pitfalls

• Missing or expired access token. The Desk API will return an authentication error if the token has lapsed. Always verify the token's expiry timestamp before making calls, and implement a refresh flow that updates your stored credentials automatically. ^[4]

• Incorrect or missing orgid. Zoho Desk is organisation-scoped, meaning every API call must be associated with a valid orgid. If this value is blank or wrong, the request will fail silently or return a permissions error. Auto-discover the org_id on first connection and store it persistently. ^[4]

• Insufficient OAuth scopes. If your application was authorised without the correct Desk scopes, pin-removal calls may be blocked. Review the full list of required scopes — including Desk.tickets.ALL, Desk.settings.ALL, and related permissions — and re-authorise if necessary. ^[1]

• Running destructive operations outside a sandbox. When testing pin removal in bulk or as part of an automated suite, always target a sandbox organisation first. The Desk test runner supports risk-level categorisation precisely to prevent accidental changes in production. ^[8]

What to check

• Valid, in-scope access token: Confirm the token has not expired and includes the Desk scopes required for the resource you are unpinning. ^{[1] [4]}
• Correct orgid on every request: Verify the organisation ID is stored and being passed correctly to the ZohoDeskClient before calling /api/v1/doc/_pin_removal. ^[4]
• Successful API response: After the call, check the response body to confirm the pin was removed rather than assuming success — handle any error codes before marking the operation complete. ^[2]

---

*Beam Help provides independent expert support for Zoho products and is not official Zoho support. Always test API changes in a sandbox environment before applying them to your production helpdesk.*