Groove to Zendesk Migration: Data Mapping, APIs & Rate Limits

A Groove to Zendesk migration is a data-model translation problem. Groove is a flat shared inbox — conversations, customers, and tags — designed for small teams. Zendesk is a relational helpdesk with Organizations, Users, Tickets, Comments, Custom Objects, and a deep automation layer. The structural gap between these two systems is where data silently disappears if you don't map it explicitly.

Groove exports conversation history as JSON, not CSV, and its public APIs are in transition: Groove says its REST API is no longer in active development and points developers to GraphQL, while noting that Inbox and Knowledge Base APIs are still being built there. On the Zendesk side, historical fidelity depends on the Ticket Import API — not the standard ticket creation endpoint or the native UI importer. If you need threads, timestamps, private notes, attachments, assignees, and organization context preserved, plan for an API-led migration, a mature migration tool, or an engineer-led service. (help.groovehq.com)

This guide covers the API constraints on both platforms, a complete object-and-field mapping, every realistic migration method with honest trade-offs, and the edge cases that cause data loss — so your engineering team can move to Zendesk without losing ticket history or operational context.

For a broader look at Zendesk's data model and capabilities, see The Ultimate Zendesk Guide. If you need to get data out of Zendesk later, start with How to Export Tickets from Zendesk.

Why Scaling Teams Move from Groove to Zendesk

Groove works well as a lightweight shared inbox for early-stage teams. But as support volume grows past a few hundred tickets per week, the cracks appear: no SLA enforcement, limited reporting, no multi-brand support, and a flat data model that can't represent complex customer relationships.

The architectural differences matter for migration planning:

Groove treats everything as a conversation thread. Zendesk treats everything as a structured record with typed fields, assignees, organizations, and SLA policies. Your migration script is the translator between these two worldviews.

In practice, teams usually leave Groove when shared-inbox simplicity stops being enough: more mailboxes, more agents, stricter permissions, separate brands, heavier routing logic, or reporting requirements that need stronger object relationships. Groove still works well when simplicity is the goal — Groove-to-Zendesk usually happens when operational complexity becomes the bottleneck. (developer.groovehq.com)

Data Model Mapping: Translating GrooveHQ to Zendesk

This section determines whether your migration succeeds or silently drops data. Every Groove object needs an explicit Zendesk target, and every field transformation must be defined before you write code.

Object-Level Mapping

Field-Level Mapping

Organization Membership Constraints

Zendesk organizations are not infinitely flexible. On Team plans, users can belong to only one organization. On other plans, users can belong to multiple organizations (up to 300), but each ticket can only belong to one organization. A Groove customer tied to multiple business entities, or a shared support email used across subsidiaries, needs an explicit default organization strategy before import. (support.zendesk.com)

If you have CRM-like entities beyond the helpdesk itself, map accounts and companies to Zendesk organizations first. Map contacts to Zendesk users. Do not force leads, opportunities, or pipeline data into support tickets — keep them in the CRM or model them in Zendesk Sell.

Handling Zendesk Custom Objects

If you need to carry over structured data that doesn't fit into Zendesk's standard ticket/user/org model, Custom Objects are your option. But know the constraints:

• Each custom object record has a maximum size of 32 KB
• Each object supports up to 100 custom fields (standard fields like name don't count)
• Accounts cannot exceed 50 million custom object records
• Lookup relationship fields are limited — 5 per object on Team/Growth plans, 10 on Professional and above
• Plan-dependent object counts: depending on your Zendesk plan, you get 3, 5, 30, or 50 custom objects (developer.zendesk.com)

These limits are documented in Zendesk's custom objects guide. Custom objects work well for compact account metadata or lookup entities. They're a bad place to dump raw conversation transcripts or large denormalized blobs. If your Groove data contains heavily nested JSON metadata that you plan to map to custom objects, flatten or truncate it to stay under the 32 KB threshold.

Zendesk API Rate Limits and Ticket Import Constraints

API rate limits are the single biggest constraint that determines how long your migration takes. Get this wrong and you'll spend days debugging 429 errors.

Account-Wide Rate Limits by Plan

These are account-wide limits — every API consumer on your account shares the same bucket. During a migration, pause non-essential integrations or schedule the migration for off-hours. The High Volume API add-on is available on Growth plans and above with a minimum of 10 agent seats. It's included by default on Enterprise Plus. (developer.zendesk.com)

Endpoint-Specific Limits

Some endpoints have their own tighter constraints:

• Incremental Exports: 10 requests/minute (30 with High Volume add-on)
• Update Ticket: 30 updates per 10 minutes per user per ticket
• Update User: 5 requests/minute per user
• In-flight job limit: 30 queued or running jobs across all bulk endpoints

The Ticket Import API: Your Only Real Option for Historical Data

The standard Tickets API (POST /api/v2/tickets) stamps every ticket with now as the creation date, fires triggers, and sends notifications. That destroys your historical timeline and spams your customers.

The Ticket Import API (POST /api/v2/imports/tickets) is the only Zendesk endpoint that preserves historical timestamps. Key behaviors: (developer.zendesk.com)

• Timestamps: Set created_at, updated_at, and solved_at on tickets, and created_at on individual comments
• Triggers suppressed: Triggers don't fire on imported tickets, but will fire on subsequent updates
• SLAs not calculated: Running metrics on imported tickets produces inaccurate data — tag them with imported and exclude from reports
• No notifications: CC'd users won't receive emails on import (but will on later updates)
• Bulk endpoint: POST /api/v2/imports/tickets/create_many accepts up to 100 tickets per request and returns a job_status object you must poll
• Archival: Set archive_immediately: true for closed tickets to bypass the normal lifecycle and send them directly to the archive

For deeper context on Zendesk's import constraints, see Freshdesk to Zendesk Migration: API Limits, Mapping & Methods.

Groove-Side API Constraints

Groove's REST v1 API paginates at a maximum of 50 records per page for tickets, messages, and customers. Extraction is usually much chattier than teams expect. (groovehq.com)

Groove's REST v1 API is deprecated — Groove recommends their GraphQL v2 API for more flexibility. The REST v1 still works but receives no new features. However, Groove notes that Inbox and Knowledge Base APIs are still being built on GraphQL, so real migrations often use a hybrid extraction strategy: REST for tickets and messages, GraphQL for newer entities. (developer.groovehq.com)

Attachment Constraints

Zendesk attachments follow a two-step process: upload the file via POST /api/v2/uploads to get a single-use token, then attach that token to a comment. Zendesk documents a 50 MB file size limit and a 60-minute token expiry window. (developer.zendesk.com)

Groove attachments are message-scoped, with a cap of 25 attachments and 20 MB per attachment per message. (doc.groovehq.com) Groove won't exceed Zendesk's per-file size limit, but Groove attachment URLs may expire. Download all attachments during the extraction phase and store them locally before uploading to Zendesk.

Migration Methods Compared

There are five realistic paths from Groove to Zendesk. Each trades off control, cost, and risk differently.

Method 1: Groove Export + Zendesk Data Importer

How it works: Request a Groove export from Settings → Company → More → Exports. Groove provides data in JSON only — there is no CSV export option. Download links expire quickly, so grab the file immediately. Large exports can take up to 72 hours. (help.groovehq.com)

Transform the JSON into CSV for user and organization data, then use Zendesk's data importer, which can handle up to 1 GB with a recommended maximum of 500,000 rows and 200 columns. (support.zendesk.com)

The catch: Zendesk's native importer handles users and organizations — not tickets. Conversation threads, attachments, timestamps, and multi-comment histories are lost entirely via this path.

For a detailed breakdown of CSV migration trade-offs, see Using CSVs for SaaS Data Migrations.

Method 2: Custom API-to-API Migration Script

How it works: Build a script that reads from Groove's API (REST v1 or GraphQL v2), transforms the data, and writes to Zendesk's Ticket Import API.

This gives you full fidelity — but it's 2–4 weeks of engineering work for a senior developer, plus testing.

Method 3: Third-Party Migration Tools

Tools like Help Desk Migration offer automated Groove-to-Zendesk migration with a GUI-based mapping interface. Zendesk lists Help Desk Migration in its marketplace as supporting Groove among 76 platforms, with field mapping, delta migration, inline-image handling, and a 20-record demo. (zendesk.com)

Method 4: Custom ETL Pipeline

How it works: Extract Groove data to a staging database or object store. Build normalized tables for customers, org keys, tickets, messages, attachments, tags, and crosswalk IDs. Run deterministic transforms and dedupe rules. Load Zendesk reference objects first, then tickets in controlled batches. Replay deltas until cutover, with rollback checkpoints and audit logs.

Method 5: Middleware Platforms (Zapier, Make)

How it works: Listen to Groove webhooks or poll source APIs. Transform events in a low-code platform. Create or update Zendesk records. Groove itself points non-developers to Zapier as the easy integration route. (doc.groovehq.com)

Middleware tools are useful for bridging the gap during a phased cutover — syncing new Groove tickets to Zendesk in real-time while you migrate historical data separately. They are not a migration tool.

Comparison Table

Picking the Right Approach

• < 500 tickets, no custom fields: Third-party tool or lightweight API script
• 1K–20K tickets, standard setup: Third-party tool with post-migration audit, or managed service
• 20K+ tickets, custom fields, attachments: Custom API script or managed migration service
• Enterprise, multi-mailbox, zero downtime: Staged ETL or engineer-led service
• Ongoing sync needed: Historical backfill via API, then webhook-driven delta sync

Step-by-Step Migration Architecture

Here's the extract → transform → load pipeline for an API-based Groove-to-Zendesk migration.

Step 1: Extract Data from Groove

Start with a full export for safety: Settings → Company → More → Exports. The export is queued — large exports can take up to 72 hours. You'll get a GZIP file containing JSON in Groove's v1 Tickets API format. Download links expire quickly. (help.groovehq.com)

For programmatic extraction, use Groove's REST v1 API or GraphQL v2 API to paginate through tickets, messages, customers, and agents. For active cutovers, add Groove webhooks to capture customer_replied, agent_replied, note_added, and ticket-state events after the initial load. (doc.groovehq.com)

import requests
import time
 
GROOVE_TOKEN = "your_groove_api_token"
BASE_URL = "https://api.groovehq.com/v1"
 
def get_groove_tickets(page=1):
    headers = {"Authorization": f"Bearer {GROOVE_TOKEN}"}
    resp = requests.get(
        f"{BASE_URL}/tickets",
        headers=headers,
        params={"page": page, "per_page": 50}
    )
    if resp.status_code == 429:
        time.sleep(int(resp.headers.get("Retry-After", 60)))
        return get_groove_tickets(page)
    resp.raise_for_status()
    return resp.json()
 
def get_messages(ticket_number):
    headers = {"Authorization": f"Bearer {GROOVE_TOKEN}"}
    resp = requests.get(
        f"{BASE_URL}/tickets/{ticket_number}/messages",
        headers=headers
    )
    resp.raise_for_status()
    return resp.json()

Step 2: Transform and Clean

Normalize email casing, strip dead test tags, decide which company_name values are real organizations, convert Groove private notes into Zendesk private comments, and flatten custom fields into a documented target-field map. If a source field has no stable target, decide now whether it belongs in a custom object, a plain text field, or nowhere at all.

Choose your cutover pattern early:

• Big bang: simplest mentally, highest operational risk
• Phased: safer when brands or mailboxes can move independently
• Incremental / delta: best when support cannot pause, using Groove webhooks to capture changes during the migration window

Step 3: Pre-Create Users and Organizations in Zendesk

Zendesk tickets reference users and organizations by ID. These records must exist before you import tickets — Zendesk will reject a ticket if the requester doesn't exist. Your pipeline must extract Groove customers, transform them into Zendesk Users and Organizations, load them, capture the new Zendesk IDs, and map those IDs to the tickets before loading conversation history. (developer.zendesk.com)

import requests
import base64
 
ZD_SUBDOMAIN = "yourcompany"
ZD_EMAIL = "admin@yourcompany.com"
ZD_TOKEN = "your_zendesk_api_token"
 
def create_zendesk_users(user_batch):
    """Batch create up to 100 users per request."""
    url = f"https://{ZD_SUBDOMAIN}.zendesk.com/api/v2/users/create_many"
    auth_str = f"{ZD_EMAIL}/token:{ZD_TOKEN}"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Basic {base64.b64encode(auth_str.encode()).decode()}"
    }
    payload = {"users": user_batch}
    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        return create_zendesk_users(user_batch)
    resp.raise_for_status()
    return resp.json()

Build a lookup map of {email: zendesk_user_id} after user creation. You'll need it for every ticket import. If you are using multiple support addresses or brands, configure those before loading tickets so routing logic is consistent.

Step 4: Transform and Import Tickets

For each Groove conversation, build a Zendesk Ticket Import payload with all comments:

def transform_groove_ticket(groove_ticket, messages, user_map):
    """Transform a Groove conversation into a Zendesk import payload."""
    comments = []
    for msg in messages:
        author_email = msg.get("author", {}).get("email", "")
        comments.append({
            "author_id": user_map.get(author_email),
            "html_body": msg.get("body", ""),
            "public": not msg.get("note", False),
            "created_at": msg.get("created_at")
        })
 
    status_map = {
        "opened": "open",
        "pending": "pending",
        "closed": "closed",
        "unread": "new"
    }
 
    return {
        "external_id": f"groove:{groove_ticket.get('number')}",
        "subject": groove_ticket.get("title", "(no subject)"),
        "requester_id": user_map.get(groove_ticket.get("customer_email")),
        "assignee_id": user_map.get(
            groove_ticket.get("assignee", {}).get("email")
        ),
        "status": status_map.get(groove_ticket.get("state"), "open"),
        "tags": [t.lower().replace(" ", "_") for t in groove_ticket.get("tags", [])]
                 + ["imported", "groove_migration"],
        "comments": comments,
        "created_at": groove_ticket.get("created_at"),
        "updated_at": groove_ticket.get("updated_at")
    }
 
def import_tickets_batch(tickets):
    """Import up to 100 tickets via Ticket Import API."""
    url = f"https://{ZD_SUBDOMAIN}.zendesk.com/api/v2/imports/tickets/create_many"
    auth_str = f"{ZD_EMAIL}/token:{ZD_TOKEN}"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Basic {base64.b64encode(auth_str.encode()).decode()}"
    }
    payload = {"tickets": tickets}
    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        return import_tickets_batch(tickets)
    resp.raise_for_status()
    return resp.json()

Step 5: Handle Attachments

Attachments require a two-step process:

1. Upload each file to Zendesk's Upload API (POST /api/v2/uploads) — this returns a token
2. Reference the token in the comment payload: {"uploads": ["token1", "token2"]}

Groove attachment URLs may expire. Download all attachments during the extraction phase and store them locally. Zendesk upload tokens are single-use and expire after 60 minutes, so upload and reference them in the same batch window.

For more on handling attachment pipelines, see Freshdesk to Zendesk Migration Guide.

Step 6: Migrate Knowledge Base (If Applicable)

Groove KB articles map to Zendesk Guide:

• Groove KB Categories → Zendesk Sections
• Groove KB Articles → Zendesk Articles

Use the Help Center API (POST /api/v2/help_center/sections/{id}/articles) to create articles with preserved authorship and timestamps where possible. This migration is independent of tickets and can run in parallel.

Step 7: Run Delta Sync and Cut Over

For zero-downtime cutovers, use Groove webhooks to capture tickets created or updated during the migration window. Replay these as a final delta pass before switching mail forwarding, widgets, or routing to Zendesk. Only then switch the production environment.

Error-handling rules worth implementing:

• Back off on 429 responses and slow batch concurrency when remaining rate budget is low
• Stop enqueuing new bulk jobs when the in-flight job budget (30) is near zero
• Quarantine tickets whose requester, org, or assignee cannot be resolved
• Log source ticket ID, source message ID, target ticket ID, batch ID, and job ID for every load step
• Never trust a completed batch without sampling the actual records

Edge Cases That Cause Silent Data Loss

These are the issues we see on real migrations — not theoretical risks.

Duplicate Customer Records

Groove identifies customers by email. If the same person has contacted you from multiple email addresses, they'll exist as separate Groove customers. In Zendesk, you can merge identities, but you need to decide before import whether to consolidate or keep separate records. Zendesk's CSV importer will also reject rows when an external ID, email, or phone matches more than one existing user. (support.zendesk.com)

Missing or Null Assignees

If a Groove ticket has no assignee, the Zendesk import still works. But if the assigned agent's email doesn't exist in Zendesk, the import silently drops the assignment. Pre-create all agents first and validate the email-to-ID map. Quarantine tickets whose assignee cannot be resolved rather than letting them import with dropped assignments.

Private Notes Leaking as Public Comments

Groove messages expose a note boolean. That must map to Zendesk private comments with public: false, or you will leak internal context to end users. This is a one-way mistake — once a customer sees an internal note, you can't unsee it. (doc.groovehq.com)

HTML Body Differences

Groove stores message bodies as HTML. Zendesk accepts html_body on comments, but sanitizes aggressively — inline styles may be stripped, and certain HTML elements get rewritten. If HTML bodies include inline images, test them explicitly. Third-party migration vendors advertise inline-image handling as a special option for a reason. (doc.groovehq.com)

Conversations with 100+ Messages

Some long-running threads in Groove can have dozens or hundreds of messages. The Ticket Import API accepts multiple comments per ticket, but very large payloads can timeout. Break extremely long threads into manageable chunks or increase your HTTP timeout.

Ticket Status Mapping Gaps

Groove uses opened, pending, closed, and unread. Zendesk uses new, open, pending, on-hold, solved, and closed. There's no 1:1 match for unread — Zendesk's new is the closest approximation. Closed tickets in Zendesk are immutable — they cannot be reopened or updated after import. Map carefully.

API Failures and Job Queue Saturation

High-volume imports fail less from bad code than from impatient code. Both Groove and Zendesk APIs return 429 errors under load. Your script must:

• Read the Retry-After header and sleep for that duration
• Implement exponential backoff for consecutive failures
• Log every failed request with the full payload for replay
• Use external_id on Zendesk ticket creation to prevent duplicates on retry
• Stop enqueuing new bulk jobs when the in-flight job limit (30) is near capacity

Zendesk Limitations to Communicate to Stakeholders

Be honest about what changes when you move to Zendesk, and what architectural constraints affect imported data:

• No equivalent of Groove Folders as live queues. Rebuild as Zendesk Views with filter conditions.
• Closed tickets are permanently locked. Once a ticket is closed in Zendesk, it cannot be updated. Import closed tickets with archive_immediately: true.
• SLAs and metrics don't apply to imported tickets. Zendesk's documentation states this explicitly. Tag imported tickets with imported and exclude them from SLA reports.
• New ticket IDs. Zendesk assigns its own IDs. Old Groove ticket numbers are gone unless you store them in external_id or a custom field.
• Triggers resume on updates. Triggers don't fire on import, but will fire on any subsequent updates to imported tickets. Audit your triggers before importing.
• No side conversation import. If Groove threads include collaborative threads or side channels, the Ticket Import API has no mechanism for side conversations.
• Custom objects are plan-limited and record-size-limited. Don't use them as a free-form escape hatch for data that doesn't fit the standard model.

Validation and Testing

Do not go live until you've validated at every level. A 200 OK response does not mean the data is correctly formatted.

Record Count Checks

Run these counts after every migration pass. Even a 1% delta means something was dropped.

Field-Level Sampling

Pull 50 random tickets — pick ugly records on purpose: old tickets, multi-reply threads, tickets with attachments, merged users, deleted agents. For each, verify:

• Subject matches
• All comments present in correct chronological order
• Timestamps preserved (created_at shows the original date, not today)
• Assignee correct
• Tags transferred and properly normalized
• Attachments downloadable
• Private notes still private

UAT Process

1. Run a test migration against a Zendesk sandbox — never go directly to production
2. Have 3–5 agents review their own historical tickets
3. Verify Views and triggers work against imported data
4. Test search — can agents find old tickets by customer name, subject, tag?

For a detailed validation checklist, see Post-Migration QA: 20 Tests to Run After Your Helpdesk Migration.

Rollback Planning

Before going live, document a rollback procedure:

• Tag all imported records with groove_migration so they can be bulk-identified
• Keep Groove accessible (read-only) for at least 30 days post-migration
• Export a full backup of your Zendesk sandbox after the test migration as a restore point
• Store a checkpoint of last migrated ticket/message IDs and webhook event timestamps so you can replay deltas cleanly if the first cutover misses something

Post-Migration Tasks

The data is in Zendesk. Now make it operational.

• Rebuild automations. Groove rules don't transfer. Recreate them as Zendesk triggers, automations, and macros. Audit every Groove rule and map it to Zendesk's trigger conditions.
• Configure Views. Replace Groove Folders with Zendesk Views. Use the same filter logic, adapted to Zendesk's field names.
• Update integrations. Any tool that pointed at Groove's API (Zapier zaps, Slack notifications, CRM syncs) needs to be re-pointed to Zendesk webhooks or API.
• Disable welcome emails. Turn off Zendesk welcome emails before user import to avoid spamming customers.
• Train agents. Zendesk's agent workspace is structurally different from Groove's inbox. Run 2–3 training sessions focused on ticket handling, macros, and the new search interface.
• Exclude imported tickets from reports. Filter by the imported tag to prevent skewed SLA metrics.
• Monitor for 30 days. Watch for: missing tickets reported by agents, incorrect assignees, broken attachments, and customers who don't appear in search.

Best Practices Checklist

• Back up Groove data before starting. Request a full export and store the JSON archive.
• Run a test migration against a Zendesk sandbox first. Never go directly to production.
• Pre-create all users and organizations before importing tickets.
• Use the Ticket Import API, not the standard Tickets API, to preserve timestamps.
• Tag all imported tickets with imported and groove_migration for filtering and reporting.
• Set archive_immediately: true for closed tickets to skip the lifecycle.
• Disable welcome emails in Zendesk before user import.
• Build and maintain an ID mapping table (Groove ID → Zendesk ID) for all objects.
• Use external_id for idempotency and safe reruns.
• Validate record counts after every migration pass.
• Field-level sample at least 50 random tickets for accuracy.
• Keep Groove in read-only mode for 30 days post-migration as a safety net.
• Freeze config changes — no new fields, groups, or routing changes during the migration window.

When to Use a Managed Migration Service

Build in-house when:

• You have a senior developer with 2–4 weeks of available bandwidth
• Your dataset is under 10K tickets with minimal custom fields
• You've done API migrations before

Use a managed service when:

• Engineering time is committed to product work and can't absorb a 2–4 week project
• You have 20K+ tickets, attachments, or complex custom field logic
• You need zero-downtime cutover with delta sync
• You can't afford a failed migration that requires a rollback
• You have any two of: large attachment volume, strict timestamp fidelity, multiple mailboxes, custom mapping, or low tolerance for downtime

The hidden cost of DIY isn't the initial script — it's the second and third scripts you end up writing for ID crosswalks, attachment uploads, 429 handling, job queue pacing, and UAT diffs. A missed edge case (null assignee, expired attachment URL, rate limit cascade) can take days to diagnose and fix. Multiply that by every object type and you're looking at significant unplanned engineering time.

ClonePartner builds custom migration scripts that handle Zendesk's 429 rate limits, 100-ticket batch constraints, the 30-job in-flight limit, and the Ticket Import API's specific requirements. We manage the full pipeline — extraction from Groove's API, user/org pre-creation, attachment upload, ticket import with preserved timestamps, delta sync, and post-migration validation — so your engineering team stays focused on product.