App Builder recipe: High-Volume End User Exporter (5k+ Capacity)

Problem Statement

Exporting a large volume of end users based on specific tags often results in pagination limits, API rate limit errors, and missing organization data. Standard API searches cap out or fail to sideload organizations properly. This app provides a direct, highly resilient solution for extracting up to 5,000+ end-user records into a CSV file directly from the Zendesk interface.

What makes this app special

• Cursor-Based Pagination & Rate Limit Handling: The app actively monitors for 429 Too Many Requests errors and utilizes the Retry-After header to pause and automatically retry requests, safely processing 5,000+ users without crashing.

• Organization Data Resolution: The standard Search API does not support organization sideloading. This app performs a secondary batch request (show_many) in the background to ensure organization names are accurately populated in the final CSV.

• Strict End-User Filtering: The API query enforces a role:end-user filter, preventing internal agents and administrators from appearing in the exported data.

• Simplified Data Review: Instead of standard pagination, the app uses a "Load 30 more" architecture for reviewing data on-screen, avoiding complex client-to-server page mapping bugs before triggering the full export.

Core use cases

• Bulk editing or scrubbing of end user data prior to re-importing via the Zendesk bulk importer.

• Syncing segmented user lists with external programs, such as CRMs, billing systems, or external databases.

• Extracting targeted communication lists (e.g., users with specific tags) for use in external email marketing tools.

• Generating compliance or account audit reports containing user creation dates and accurate organization mappings.

Location of app

Side Navigation, for complex apps that need space

The Recipe (The Prompt)

Role: Act as an expert Zendesk App Developer using the Zendesk App Framework (ZAF) and React.

Goal: Create a custom Zendesk app (designed for the nav_bar location) that allows agents to search for End Users by up to three specific tags and export the complete list of matching users to a CSV file. The app must be highly resilient, capable of exporting 5,000+ users without timing out.

UI & Input Requirements:

• Tag Input: Create a single multiselectable Combobox for tag entry.

  • On load, fetch the top 100 popular tags via GET /api/v2/tags to pre-populate suggestions.

  • Implement autocomplete: when the user types 2+ characters, call GET /api/v2/autocomplete/tags?name={input} (debounced by 300ms) for live suggestions.

  • Limit the input to a maximum of 3 selected tags.

  • Allow custom tags to be entered even if they don't appear in the suggestions.

• Action Buttons: A "Search" button and an "Export to CSV" button.

Data Display & Table Requirements:

• Results Table: Display Name, Email, Organization, and Created Date (YYYY-MM-DD).

• Sortable Headers: Make all four column headers sortable (client-side sorting on the currently loaded data), toggling between ascending and descending.

• Clickable Names: Fetch the account subdomain via zafClient.get('currentAccount.subdomain'). Wrap the user's name in a link that opens their profile in a new tab: https://{subdomain}[.zendesk.com/agent/users/](https://.zendesk.com/agent/users/){id}.

• "Load More" Display: Do not use offset pagination pages. Instead, show the first 30 users and provide a "Load 30 more" button at the bottom. When clicked, reveal 30 more rows. When the visible count exhausts the in-memory API data, automatically fetch the next API page and append it. Include a meta text line: "Showing X of Y users".

Search API Logic Requirements:

• Search Logic: Use client.request() to call /api/v2/search.json with a per_page=100 limit.

• Query: Build the query using OR logic for the tags and ensure it filters out agents. Example: type:user role:end-user tags:{tag1} OR tags:{tag2}.

• Organizations (CRUCIAL): The Search API does not support standard sideloading for organizations. Instead, after fetching a page of users, extract all unique organization_ids, then call GET /api/v2/organizations/show_many?ids=... to resolve the organization names in a single batch request. Maintain a map of these IDs to avoid re-fetching the same organizations.

Export & High-Volume Scale Requirements (5,000+ Users):

• Export Endpoint: Use the /api/v2/search/export endpoint (not the standard search endpoint) to bypass the 1,000-result cap. Use cursor-based pagination (page[after] or links.next) to fetch 100 users per page.

• Rate Limit Handling: Implement strict 429 (Too Many Requests) protection. If triggered, read the Retry-After header and wait that exact duration before automatically retrying (up to 5 times).

• Progress Indicator: Show a real-time progress bar or updating text (e.g., "Fetching page X...") while the CSV is being compiled.

• CSV Generation: Accumulate all results in memory, properly escape all cells (handling commas/quotes), and convert to a CSV string. Use a Blob (text/csv;charset=utf-8;) to trigger a download named user_export_YYYY-MM-DD.csv. Exclude agents from the export. Use the previously built organization map to populate the Organization column without making additional API calls during the export loop.