Kustomer to Groove Migration: The Complete Technical Guide

Kustomer to Groove Migration: The Complete Technical Guide

Migrating from Kustomer to Groove is a structural downshift in data model complexity. Kustomer is a CRM-helpdesk hybrid that stores every customer interaction — emails, chats, custom events, and third-party data — as a continuous, chronological timeline per customer record. Groove is a flat shared inbox: each conversation is a discrete ticket with messages, tags, and a state. The customer is the top-level object in Kustomer; the ticket is the top-level object in Groove.

There is no native migration path between these two systems. Kustomer has no built-in Groove export, and while Groove's migration partner (Import2) lists both platforms as supported apps, the practical route for anything beyond basic conversations is Kustomer API extraction → data transformation → Groove API loading.

This is not a CSV copy-paste. When you move from a complex, timeline-based data model to a discrete, ticket-based system, data mapping becomes the primary engineering challenge. This guide covers the exact object mapping, API constraints on both sides, extraction strategies, KObject handling, Groove's deduplication behavior, timestamp backdating confirmation, and the failure modes that derail teams mid-migration.

For details on getting data out of Kustomer, see our guide on How to Export Data from Kustomer. For other Kustomer migration targets, see our Kustomer to Zendesk guide or Kustomer to Gorgias guide.

Why Teams Move from Kustomer to Groove

The migration usually comes down to cost, complexity, and team size:

• Price. Kustomer's Enterprise plan starts at $89/seat/month with an 8-seat minimum and annual-only billing — that's a floor of ~$8,500/year before AI add-ons. Groove's Standard plan starts around $20–29/user/month with no seat minimums.
• Simplicity. Kustomer's CRM-grade data model (custom Klasses, KObjects, workflows engine, timeline views) is powerful but operationally heavy for teams that just need a shared inbox. Groove is purpose-built for small and mid-size teams that want email, live chat, and a knowledge base in one clean workspace.
• Reduced operational overhead. Kustomer's implementation costs run $18,000–$30,000 with a 12–16 week lead time. Groove requires near-zero implementation effort.
• Team size. Groove targets teams of 1–50 agents. Kustomer targets mid-market and enterprise with high-volume B2C support.

Kustomer vs. Groove: Data Model Comparison

Understanding the structural mismatch is the first step to a clean migration. Here's how the two platforms differ at the data model level:

The biggest translation challenges:

1. Kustomer's customer-centric model → Groove's ticket-centric model. In Kustomer, the customer is the top-level object and conversations are nested under it. In Groove, tickets are independent objects linked to a customer email. You lose the unified timeline view.
2. KObjects have no Groove equivalent. Any custom object data (orders, subscriptions, reservations) stored in KObjects cannot be natively represented in Groove. You must either flatten this data into ticket tags/custom fields, append it as notes, or archive it externally.
3. Multi-channel conversations become separate tickets. A Kustomer conversation that spans email and chat is one object. In Groove, these will need to be separate tickets or merged into a single thread with channel metadata preserved in the body.

Object-by-Object Field Mapping

Map Kustomer's data to Groove's schema before writing a single line of extraction code. Surprises at load time are expensive.

Customers → Customers

Groove Contact Deduplication Behavior

When loading customers into Groove, email address is the deduplication key. If two Kustomer customer records share the same email (possible if Kustomer was used without strict deduplication), Groove will create separate contact records for each — it does not automatically merge on import.

If you have a Kustomer customer with multiple email addresses (Kustomer supports this), only the primary email maps cleanly to Groove. Secondary emails must be appended as notes or discarded. Before loading, run a deduplication pass on your extracted customer dataset: group records by email and merge any Kustomer duplicate customers into a single canonical record. Tickets from both source records should then be loaded under the merged contact.

Conversations → Tickets

Kustomer uses a flat tag structure. Groove uses Folders for primary organization and Tags for secondary categorization. Define a logic rule to split Kustomer tags between Groove folders and tags before loading.

Messages → Messages

Knowledge Base Articles

Kustomer API: Extraction Constraints

Authentication: Bearer token via API key, scoped to the organization. Generate keys under Settings → Security → API Keys.

Base URL: https://api.kustomerapp.com/v1 (US-hosted). For EU-hosted instances, use https://api.prod2.kustomerapp.com/v1.

Rate limits are organization-wide and vary by plan:

These limits are counted across all API keys in the organization. If other integrations are running during migration — webhooks, live chat connectors, CRM syncs — they share the same budget. Schedule extraction during low-traffic windows or monitor X-RateLimit-Remaining headers on every response.

Which integrations to disable during extraction: Before starting, audit active Kustomer integrations under Settings → Integrations. Pause or temporarily disable: outbound webhook subscriptions, Shopify/BigCommerce event connectors, any Zapier or Make (Integromat) workflows polling the Kustomer API, and any third-party BI or analytics tools with live Kustomer API connections. Each of these consumes rpm from the same organization-wide budget as your migration scripts.

A production-grade migration script should inspect X-RateLimit-Remaining on every response. If the value drops below a safe threshold (e.g., 5), pause execution until the X-RateLimit-Reset timestamp. Relying strictly on catching 429 Too Many Requests errors will result in dropped payloads.

Pagination: Cursor-based using page [size] (max 100) and page [after] parameters. Your ETL pipeline must capture the next cursor and append it to subsequent requests. If a network timeout occurs during page 45 of a 50-page extraction, the script must resume from the last known cursor rather than restarting.

{
  "meta": {
    "pageSize": 100,
    "page": 1,
    "next": "eyJmaWx0ZXJzIjpbeyJvcCI6ImVxIiwiZmllbG..."
  },
  "data": [ ... ]
}

The Search API has a hard limit of 100 pages per query. For datasets exceeding this, use date-range filters and advance the gte timestamp with each batch.

Extraction sequence:

1. Teams and Users — GET /v1/teams, GET /v1/users
2. Tags — GET /v1/tags (resolve tag IDs to human-readable names)
3. KObject Klass enumeration — GET /v1/kobjects to retrieve all defined Klass names, then fetch schemas via GET /v1/kobjects/{klassName}
4. Customers — GET /v1/customers with cursor pagination
5. Conversations per customer — GET /v1/customers/{id}/conversations
6. Messages per conversation — GET /v1/conversations/{id}/messages (page size max 100)
7. Attachments — Download from URLs in message bodies
8. KObjects per customer — GET /v1/customers/{id}/kobjects/{klassName} for each Klass name retrieved in step 3
9. KB Articles — GET /v1/kb/articles

KObject Klass Discovery

Before you can extract KObject data, you need the list of all Klass names defined in your Kustomer instance. Kustomer stores these as system-defined and custom schemas. To enumerate them:

GET /v1/kobjects

This returns a list of all Klass definitions including their names, field schemas, and whether they are system-generated or custom. For each Klass returned, fetch associated records per customer:

GET /v1/customers/{customerId}/kobjects/{klassName}

Some Klasses are created automatically by integrations (e.g., Shopify installs a shopify_order Klass). Others are defined manually by your team. Audit all Klasses before deciding your flattening strategy — some will contain rich operational data; others may be unused or redundant.

Groove API: Loading Constraints

Groove offers two APIs: the REST v1 API and the GraphQL v2 API.

REST v1 (https://api.groovehq.com/v1) is the legacy API. It authenticates via a Bearer access token and supports tickets, messages, customers, agents, and tags. Groove's own documentation notes that the REST API is no longer in active development and new features are being built exclusively in GraphQL v2.

Key REST v1 endpoints for migration:

• POST /v1/tickets — Create a ticket (requires body and from at minimum)
• POST /v1/tickets/{number}/messages — Add a message to a ticket
• POST /v1/customers — Create a customer
• PUT /v1/tickets/{number}/tags — Set tags on a ticket
• PUT /v1/tickets/{number}/state — Set ticket state
• PUT /v1/tickets/{number}/assignee — Set assignee

GraphQL v2 is Groove's recommended API going forward. It provides read/write access to conversations, messages, agents, contacts, mailboxes, tags, and knowledge base data.

Timestamp Backdating: Which API Works

This is the single most important technical question in a Groove migration, and the answer is version-dependent:

• Groove GraphQL v2: Accepts createdAt on both ticket and message creation mutations. When set, the ticket and message timestamps in the Groove UI reflect the original Kustomer dates. This is the correct API to use for preserving chronological order.
• Groove REST v1: Does not reliably support created_at backdating on ticket or message creation. Records loaded via REST v1 will reflect the timestamp at the time of API call, not the original Kustomer timestamp. Do not use REST v1 for historical migrations if chronological integrity matters.

Conclusion: Use Groove GraphQL v2 for all ticket and message creation. Verify this in a test account with a small batch (10–20 tickets) before committing to the full run — API behavior can change with platform updates.

mutation CreateHistoricalTicket($input: TicketCreateInput!) {
  ticketCreate(input: $input) {
    ticket {
      id
      state
      createdAt
    }
    errors {
      message
      path
    }
  }
}

Groove GraphQL Rate Limits

Groove does not publish specific rate limit numbers in its public documentation. Based on observed behavior and community-reported findings (as of 2024):

• Groove's GraphQL API returns HTTP 429 responses when limits are exceeded, with a Retry-After header indicating the backoff period
• The API uses query complexity scoring rather than simple request-per-minute counts. A mutation creating a ticket with nested messages and attachments costs significantly more than a simple read query
• Observed practical throughput for ticket creation mutations: approximately 200–400 operations per minute under normal conditions, dropping significantly with complex nested mutations or large attachment payloads
• Groove has not publicly confirmed these numbers; treat them as empirical starting points, not guarantees

Build backoff logic into your migration script from the start: on receiving a 429, read the Retry-After header value and sleep for that duration before retrying. Do not implement fixed sleep intervals — these waste time on fast runs and fail on slow ones.

Idempotency: Groove does not natively upsert based on external IDs. You must maintain a local mapping database (Kustomer ID → Groove ID) to prevent duplicate ticket creation if the migration script fails and restarts.

GraphQL partial errors: In REST, a 200 OK generally means success. In GraphQL, a request can return a 200 OK but contain an errors array in the response payload. Your migration script must explicitly check for the errors array in every Groove response. If an error is detected, log the failed Kustomer Conversation ID, the exact error message, and continue processing the next record.

Groove Sandbox Environment

Groove does not offer a dedicated sandbox or staging environment on standard plans. The standard workaround for pre-migration testing is:

1. Create a separate Groove account using a test email domain (e.g., yourdomain-migration-test@groovehq.com)
2. Use this throwaway account for all pilot batch validation
3. Confirm timestamp backdating, tag behavior, attachment rendering, and private note visibility before running against production
4. Delete the test account after validation is complete

Handling KObjects and Custom Events

Kustomer's defining feature is its ability to ingest custom objects (KObjects) like Shopify orders, Jira tickets, or proprietary backend events directly into the customer timeline. Groove has no custom object system.

This is the single biggest data-loss risk in a Kustomer-to-Groove migration. KObject data is often the most operationally valuable data in Kustomer, and losing it silently is the most common regret teams report post-migration.

You have three options:

1. Flatten into tags or custom fields — Lossy, but keeps key metadata searchable in Groove.
2. Append as formatted private notes — Preserves full data, loses native structure but keeps it visible to agents on the relevant ticket.
3. Archive externally — Export to a database or S3 bucket for reference outside Groove.

The most effective approach for maintaining agent context is Event Flattening into private notes. During extraction, identify KObjects associated with a conversation. Transform the JSON payload into a readable HTML block. Inject this into the Groove ticket as a Private Note (an internal message not visible to the end customer) immediately preceding the message it relates to.

For example, a Kustomer order payload:

{
  "type": "order",
  "attributes": {
    "orderNumber": "1001",
    "totalPrice": "45.00",
    "status": "shipped"
  }
}

Becomes a Groove Private Note:

<strong>System Event: Order</strong><br>
Order Number: 1001<br>
Total Price: 45.00<br>
Status: shipped

This preserves historical context without exposing internal data to customers.

Migration Methods: Trade-Offs and Decision Framework

Complexity Scoring: Which Method to Use

Use this rubric to assess migration complexity before choosing an approach:

Score 6–8: Import2 or a light custom script is sufficient. Score 9–13: Custom API-led migration with careful QA. Score 14–18: Engineer-led migration service recommended.

Option 1: Custom API-Led Migration

Write scripts that extract from Kustomer's REST API, transform the data model, and load into Groove's GraphQL v2 API.

Pros:

• Full control over field mapping, data transformation, and error handling
• Can handle KObject flattening, channel metadata preservation, and timestamp mapping
• Can be run incrementally with delta passes

Cons:

• Requires engineering time
• Must handle rate limiting, pagination, retries, and idempotency yourself
• Groove's GraphQL v2 write documentation is less mature than its read documentation

Estimated engineering time by volume:

These estimates assume medium message density (~15 messages/conversation), moderate attachment volume, and 2–3 KObject Klasses requiring flattening. Heavy attachment volume or deeply nested custom schemas add 20–40% to both figures.

Best for: Teams with engineering resources who need precise control over data fidelity.

Option 2: Import2

Groove has partnered with Import2 for migrations. Import2 lists both Kustomer and Groove as supported apps.

What Import2 transfers (confirmed): Customers (email, name), open and closed tickets, messages (body, direction, timestamps), tags, assignees.

What Import2 does not transfer: KObject data, custom Klass schemas, multi-channel conversation metadata, sentiment scores, company associations, custom customer attributes, conversation-level SLA data, and secondary customer emails. Attachment transfer is supported but inline image rewriting is not guaranteed.

Pros:

• Lower engineering effort
• Sample migration available before committing
• Handles basic object mapping

Cons:

• KObject migration is unsupported
• Channel metadata, sentiment data, and custom attributes do not transfer
• Large datasets (100K+ conversations) may hit timeout or performance constraints

Best for: Score 6–8 on the complexity rubric above. Teams where KObject data is not operationally critical.

Option 3: Engineer-Led Migration Service

A team experienced in helpdesk migrations handles the full pipeline: extraction, transformation, loading, validation, and delta sync.

Pros:

• Handles edge cases (KObject flattening, attachment re-hosting, timestamp preservation)
• Validation and QA built into the process
• Delta migration support for zero-downtime cutover

Cons:

• External cost (typically $3,000–$15,000 depending on data volume and complexity)
• Requires sharing API credentials with the migration partner

Best for: Score 14–18 on the complexity rubric. Teams that need high data fidelity, have complex KObject schemas, or cannot afford migration failures.

Step-by-Step Migration Strategy

1. Audit Kustomer Data

Count customers, conversations, messages, KObjects per Klass, and KB articles. Enumerate all Klass names via GET /v1/kobjects. Identify data older than 2 years that requires Archive Search extraction. Score your migration on the complexity rubric above. This audit sets your expectations for timeline, API budget, and method selection.

2. Map Agents, Teams, and Inboxes

Extract all Kustomer users and teams. Build a lookup table mapping Kustomer user IDs to Groove agent emails. Pre-create all Agents, Groups, and Inboxes in Groove with matching names. Store the Kustomer userId → Groove agentId mapping in a local key-value store. This mapping table is required for every subsequent API call to assign tickets and attribute message authorship.

3. Resolve Tags and Decide on KObject Handling

Export all Kustomer tag IDs to human-readable names via GET /v1/tags. Decide your KObject strategy — flatten, append as notes, or archive externally — for each Klass. Define which Kustomer tags map to Groove tags vs. Groove folders.

4. Provision Groove Test Account and Validate Timestamp Behavior

Create a throwaway Groove account. Load 20–50 test tickets via the GraphQL v2 API with explicit createdAt values set to historical dates. Verify in the Groove UI that:

• Ticket creation dates reflect the original Kustomer dates (not the import timestamp)
• Message timestamps within tickets reflect the original message sentAt values
• Private notes are not visible to the customer-facing contact

If timestamps are not preserved correctly, stop and resolve before proceeding. All subsequent QA depends on this working.

5. Export and Create Customers

Run deduplication on the extracted customer dataset — merge records sharing the same email. Insert the deduplicated set into Groove via the API, capturing the returned Groove customerId for ticket association. Store the Kustomer customerId → Groove customerId mapping locally.

6. Extract Conversations, Messages, and Attachments

For each Kustomer conversation:

1. Fetch the conversation metadata.
2. Fetch all associated messages (handling pagination for long threads).
3. Fetch all associated attachments.
4. Fetch KObjects associated with this conversation's customer (matching by timeline proximity if needed).
5. Bundle this into a single JSON object locally before any API calls to Groove.

Attachment handling: Kustomer stores attachments in secure S3 buckets accessible via expiring URLs. Your script must download each file into local memory, then upload it to Groove using the attachmentCreate mutation (GraphQL) or the REST attachment endpoint. Attach the returned ID to the corresponding message creation call.

Inline images: Parse the Kustomer message HTML body for <img> tags pointing to Kustomer's CDN. Download these images, upload them to Groove, and rewrite the src attribute in the HTML body before sending it to Groove. Failure to do this results in broken images when Kustomer deactivates your account.

7. Test a Pilot Batch

Migrate 50–100 conversations into your test Groove account and validate:

• Message ordering and thread integrity
• Attachment accessibility (click and open, don't just check that the link exists)
• Tag and assignee accuracy
• Historical timestamps on tickets and messages
• KObject private notes marked as internal (not visible to customers)
• Deduplicated contacts — no duplicate customer records

If any check fails, fix the script before proceeding to full load.

8. Load Data via Groove API

Run the full migration with rate limiting, retries, and progress logging. Use Groove GraphQL v2 for all ticket and message creation to ensure timestamp support. For each failed record, log the Kustomer Conversation ID and the exact error. Do not stop the pipeline — continue and batch-resolve failures after the primary run.

9. Execute Delta Migration

A migration of any significant scale cannot happen in a single uninterrupted pass. Extracting and loading hundreds of thousands of tickets takes days. During this time, your business is still operating and new tickets are being created in Kustomer.

To achieve zero downtime:

1. Initial Sync: Extract all historical data up to a specific timestamp (e.g., Friday at 11:59 PM). Load into Groove. This takes the bulk of processing time.
2. Delta Sync: Run the script again, modifying the Kustomer extraction query to only fetch conversations where updatedAt > [Initial Sync Timestamp]. This captures tickets created, replied to, or closed during the initial sync.
3. Cutover: Pause incoming mail to Kustomer. Run a final, rapid Delta Sync to catch the last few minutes of activity. Update your DNS (MX records) and email forwarding rules to point to Groove. Unpause mail.

This ensures agents log into Groove with a perfectly up-to-date inbox and zero customer emails are lost in transit.

Edge Cases and Failure Modes

These are the issues that don't surface until you're halfway through a migration.

Kustomer's 2-Year Search Window

The standard Search API only returns records updated within the past 2 years. If you have older conversations, they won't appear in search results. Use the Archive Search endpoint — it accepts the same query format and returns both archived and recent records.

Timestamp Fidelity

Groove GraphQL v2 accepts createdAt on ticket and message creation. REST v1 does not reliably support backdating. Use GraphQL v2 exclusively for historical data loads. Confirm this in your test account before the full run — API behavior can change with platform updates.

Multi-Channel Conversations

A single Kustomer conversation can include messages from email, chat, SMS, and social — all in one timeline. Groove doesn't natively represent multi-channel conversations. Options:

• Merge into one ticket with channel labels in the message body (e.g., prefix each message with [SMS] or [Chat])
• Split into separate tickets per channel, linked by a shared tag (e.g., kustomer-conv-12345)

Neither option is lossless. Choose based on what your agents need when referencing historical conversations.

Tag ID Resolution

Kustomer stores tags as IDs internally. You must resolve these to human-readable tag names via GET /v1/tags before loading into Groove, which stores tags as strings. Miss this step and your tickets arrive with meaningless alphanumeric tag values.

Rate Limit Collisions

Kustomer's API rate limit is organization-wide across all API keys. Pause active Kustomer integrations (webhooks, Shopify connector, Zapier workflows, BI tools) before starting extraction. Monitor X-RateLimit-Remaining headers on every extraction request and pause when below threshold, rather than waiting for 429 errors.

Attachment URL Expiration

Kustomer hosts attachments on its own CDN with expiring URLs. After you cancel Kustomer, those URLs stop resolving permanently. Every attachment must be downloaded during extraction and re-uploaded to Groove's infrastructure. This includes inline images embedded in HTML message bodies.

Groove Contact Deduplication

Groove does not automatically merge contacts on import. If the same email appears in multiple Kustomer records, Groove creates multiple contact records. Run a deduplication pass on extracted customer data before loading. Map all source Kustomer IDs that share an email to a single canonical Groove contact ID in your local mapping database.

What You Lose in the Migration

Be explicit with stakeholders about what doesn't survive the move:

• Unified customer timeline — Groove doesn't render a single view of all interactions per customer the way Kustomer does
• KObject structured data — Custom objects don't have a native home in Groove (only flattened approximations)
• Sentiment scores and conversation analytics — Kustomer's ML-derived sentiment data has no Groove equivalent
• Business rules and workflows — Kustomer automations are not exportable and cannot be replicated in Groove's simpler rule engine
• Company associations — Kustomer's company objects have no direct Groove equivalent
• Conversation-level SLAs — Kustomer's SLA policies need to be recreated manually in Groove (if available on your plan)
• Secondary customer emails — Groove's contact model supports one primary email; secondary Kustomer emails must be appended as notes or dropped
• Multi-channel timeline integrity — A single Kustomer conversation spanning email and SMS becomes either a merged flat thread or two separate tickets

If any of these are operational requirements — not nice-to-haves — reconsider whether Groove is the right target. See our guides for Kustomer to Zendesk, Kustomer to HubSpot Service Hub, or Kustomer to Help Scout if you need more structural depth in your target platform.

Validating the Migration

Never cut over DNS or email forwarding until the data is validated. Run strict QA across your newly populated Groove instance:

• Count validation: Does the total number of Kustomer conversations match the total number of Groove tickets?
• State validation: Are Kustomer "Done" conversations correctly marked as "Closed" in Groove?
• Thread integrity: Did multi-message threads arrive in the correct chronological order?
• Attachment accessibility: Can you open attachments on Groove tickets from older conversations? Do inline images render?
• Visibility checks: Are flattened KObjects strictly marked as Private Notes so internal data isn't exposed to customers?
• Agent assignments: Are tickets assigned to the correct agents and groups?
• Timestamp spot-checks: Do random tickets show creation dates matching the original Kustomer records?
• Contact deduplication: Are there duplicate contact records in Groove for the same customer email?
• KObject coverage: For a sample of Kustomer customers with known KObject records, verify the corresponding Groove tickets contain the expected private notes

Spot-check random conversations across multiple date ranges. Automated count validation catches bulk issues; manual inspection catches subtle data corruption.

Making the Call

Kustomer to Groove is a viable migration for teams trading down from an enterprise CRM-grade platform to a simpler, cheaper shared inbox. The technical execution is straightforward when your data is primarily conversations and customer records. It gets harder when KObjects, multi-channel timelines, and historical fidelity matter.

The key decisions that determine success:

1. Score your migration complexity using the rubric above before choosing a method.
2. Enumerate all KObject Klasses via GET /v1/kobjects and decide handling strategy per Klass before extraction starts.
3. Confirm timestamp backdating works in a test Groove account before committing to the full run. Use GraphQL v2 — not REST v1.
4. Pause live Kustomer integrations before extraction to protect your rate limit budget.
5. Run contact deduplication before loading to prevent duplicate Groove contact records.
6. Plan for delta sync if your migration will take more than one business day.