How to Export Data from Puzzel Case Management: Methods & Limits

How to Export Data from Puzzel Case Management: Methods & Limits

Exporting data from Puzzel Case Management is not a one-click operation. The platform offers multiple extraction paths — a UI-based CSV ticket export, a Report Builder with scheduled exports, a tenant-specific REST API documented via Swagger, and PCM Raw Data for warehouse-style reporting — but each one has different coverage and none gives you a single complete dump of all ticket data with full message threads, attachments, and metadata in one pass.

If you are planning a migration (such as a Puzzel to Kayako migration), an archival project, or a data consolidation, you will almost certainly need to combine the CSV export with API extraction to get complete data. Most teams start by looking for an "Export All" button in the UI and quickly discover that native exports are designed for reporting, not full-scale data portability.

This guide covers every extraction method, what each one actually returns, API authentication and scoping, known limitations, pagination parameters, error handling, and the practical steps to get your data out of Puzzel Case Management cleanly.

What Is Puzzel Case Management?

Puzzel Case Management is a Case/Ticket management tool that provides contact centres and helpdesks with the ability to manage written interactions in a secure and efficient way. Each email in the queue is converted into a support ticket and assigned a unique case/ticket ID, which is then filtered, categorised, and distributed to the right team or agent.

Puzzel Case Management is part of the Puzzel suite of customer service applications and can be combined with Puzzel Contact Centre to offer a unified platform integrating ticketing and contact centre operations. (This contact-centre integration is a primary reason teams migrate to Puzzel from shared inboxes like Enchant). It supports email, SMS, and API-based ticket creation, with skill-based routing, SLA tracking, categories, forms, tags, and multi-team structures.

Puzzel Case Management Data Model: What You're Exporting

Before choosing an extraction method, understand what entities exist in the system:

The critical gap: SLA configurations, automated workflows, inbound rules, response templates, and business rules cannot be exported programmatically through any method. These must be manually documented and recreated in any target system. (This is a universal constraint in helpdesk data portability—whether you are exporting out of Puzzel or migrating into Puzzel from platforms like HappyFox, automations must be rebuilt by hand).

Method 1: CSV Ticket Export (UI)

Best for: Quick metadata exports, spot-checking, small-to-medium datasets.

Puzzel Case Management provides a built-in CSV export directly from the Tickets page in the admin interface.

How It Works

To export a specific range of tickets, go to the Tickets page and use the Ticket Attributes widget to filter the Tickets List for only those tickets you wish to export. For example, for a CSV export of Customer Service tickets from Last Week, start a Search Filter for "Team: Customer Service" and "Time Period: Last Week."

Select the Categories tab to search for tickets with specific Category choices applied — for example, "Query Type: Complaints" to export all complaint tickets. This filter is applied alongside the Ticket Attributes filter.

Bulk-select all tickets on the page using the Checkbox column header, or select specific tickets individually across multiple pages. Once your selection is complete, choose Export to CSV from the bulk update tools.

You can select as many or as few columns as required. Clicking Export creates the file and delivers it as a CSV attachment to your user email address. Delivery can take several minutes depending on the number of tickets selected.

What the CSV Export Includes

The CSV covers ticket metadata: ticket IDs, status, priority, team, assigned agent, timestamps, categories, tags, and form field values. Column selection is configurable.

What the CSV Export Does NOT Include

• Agent replies and private notes: The conversation thread is stripped out entirely.
• Inline images and attachments: Binary files cannot be represented in CSV cells.
• Full message content: Only the initial message or a truncated summary is included, not the complete thread.
• Complex custom fields: Multi-select fields and dependent dropdowns often export as unparseable strings.

CSV Export Encoding

As of the May 2022 release, Puzzel improved CSV export to correctly handle special characters (including Scandinavian letters) when loading the file into Excel. If you are working with Nordic or other non-ASCII characters, confirm you are on a post-May 2022 build.

Method 2: Report Builder (Scheduled Exports)

Best for: Operational reporting, scheduled data pulls, aggregate metrics.

The Report Builder in Puzzel Ticketing allows you to create and generate custom reports as standard. Reports can be set to generate automatically at a configured frequency and emailed as attachments.

Report Builder supports CSV, XLSX, and PDF output formats. PDF is limited to reports with 10 columns or fewer. Time-duration columns in XLS or CSV output appear in minutes.

Available columns include: New Tickets, New Manual Tickets, New Child Tickets, New Inbound Tickets, Changed To, Changed From, Tickets Resolved, Reopens, Messages Received, outbound activity, SLA performance indicators, parent/child ticket references, and category-level breakdowns.

You can set custom filters to Include or Exclude specific ticket attributes by selecting the Add Filter button, choosing Include or Exclude, selecting the attribute type, and then the specific attribute values.

Report Builder Limitations

The Report Builder is an analytics tool, not a data extraction tool. It produces aggregate and per-ticket metric reports — not raw ticket content with full conversation threads. It is useful for auditing extraction completeness or generating KPI packs but does not replace API extraction for a migration.

Method 3: REST API (Full Data Extraction)

Best for: Complete data extraction, migrations, integrations, programmatic access.

The Puzzel Case Management REST API is the only self-service method that provides access to full ticket content — including messages, notes, and attachment references.

API Documentation Access

The Help menu (Help → API Documentation) links directly to API documentation powered by Swagger UI. The interface allows you to browse, search, and test API endpoints interactively, with comprehensive coverage of parameters, responses, and example requests.

The Swagger documentation is tenant-specific — it is accessed from within your Puzzel Case Management instance, not from a public URL. Do not rely on generic documentation. Always reference the Swagger UI hosted on your specific tenant to confirm endpoint availability and parameter syntax for your account version.

Authentication and Scoping

To create an API channel: go to Settings > Ticket Channels > API and click the button in the top right. Select an authentication level:

• Global — access to all tickets across all organisations
• Organisation — access restricted to tickets within a single organisation

Select your Token Type: Basic Token or OAuth Token.

For a full data export, you must use Global scope. Choosing Organisation scope by mistake is a quiet failure mode that will cause you to miss all tickets from other organisations with no error or warning.

For the broader Puzzel platform, API security is based on OpenID Connect, an identity layer on top of the OAuth 2.0 protocol. Avoid setting long lifetimes for access tokens — due to signing key rotation in the Puzzel ID provider, tokens with extended lifetimes may become invalid before their stated expiration time.

Verifying Private Note Access

Private note visibility depends on your API channel's access level. When a note is marked private, it is not exposed when retrieving ticket content via a standard API channel. To verify whether your token surfaces private notes:

1. Identify a ticket in your instance that is known to contain a private note.
2. Call the Ticket Show endpoint for that ticket ID using your API token.
3. Inspect the response for the note. If the note is absent from the response, your token does not have private note access.
4. If private notes are required for your migration — and for compliance purposes they usually are — open a support ticket with Puzzel to confirm whether an elevated access level can be granted to your API channel.

There is no published flag or field in the API response that explicitly states "private note access: true." Verification requires empirical testing against known data.

API Capabilities and Evolution

Puzzel introduced the Case Management API in the July 2022 release with Ticket Create, Ticket List, Ticket Show, and Ticket Update. The surface has expanded significantly since then:

• March 2024: Tag listing, category listing, selectable category-option retrieval, and ticket search using manual-entry category or form-field values.
• June 2024: Message Content Info for querying specific email or API messages by database ID, including known related email addresses.
• August 2024: Ticket Show and Message Show gained HTML and TEXT message versions plus inline-image links. API search added complex multi-condition queries.
• February 2025: Customer and organisation create/read/update/delete support, including custom fields.
• March 2025: Reply and Inbound Message endpoints, API search sub-sorting, and IP-whitelisting enforcement for OAuth token requests.
• June 2025: Category choice endpoints gained pagination metadata and support for ?per_page=1000.

Based on the current API surface, a full extraction targets these entity types:

• Ticket list with search criteria, date-range filtering, and status filtering
• Category and form associations per ticket
• Organisation and tag lists
• Full conversation threads via Ticket Show, Message Show, and Message Content Info
• Attachment references and inline-image links (available in Ticket Show and Message Show responses since August 2024)
• Customer and organisation records with custom fields (available since February 2025)

Pagination Parameters

The Puzzel Case Management API uses page-based pagination. Key parameters:

For ticket list endpoints, iterate until the response contains fewer results than your requested page size, or until the metadata indicates you have reached the last page. Do not assume a fixed page size — validate the default against your tenant's Swagger documentation, as defaults can differ by endpoint.

API Response Structure: Representative Examples

The following are representative (simplified) structures for the two most-used endpoints. Validate against your tenant's Swagger for exact field names and types.

Ticket Show response (simplified):

{
  "ticket": {
    "id": 100042,
    "subject": "Order not received",
    "status": 2,
    "priority": 1,
    "team_id": 7,
    "assignee_id": 33,
    "customer_id": 891,
    "organisation_id": 14,
    "created_at": "2024-03-15T09:22:11Z",
    "updated_at": "2024-03-17T14:05:33Z",
    "tags": ["billing", "urgent"],
    "messages": [
      {
        "id": 500201,
        "type": "inbound",
        "body_html": "<p>Hi, I haven't received my order...</p>",
        "body_text": "Hi, I haven't received my order...",
        "created_at": "2024-03-15T09:22:11Z",
        "inline_images": [
          { "cid": "image001", "attachment_id": 9901 }
        ],
        "attachments": [
          { "id": 9902, "filename": "screenshot.png", "size": 48210, "content_type": "image/png" }
        ]
      }
    ],
    "notes": []
  }
}

Message Content Info response (simplified):

{
  "message": {
    "id": 500201,
    "ticket_id": 100042,
    "type": "email",
    "from": "customer@example.com",
    "to": ["support@yourcompany.com"],
    "cc": [],
    "bcc": [],
    "subject": "Order not received",
    "body_html": "<p>Hi, I haven't received my order...</p>",
    "body_text": "Hi, I haven't received my order...",
    "related_addresses": ["customer@example.com"],
    "created_at": "2024-03-15T09:22:11Z"
  }
}

Use Ticket Show for bulk thread extraction. Use Message Content Info when you need full To/CC/BCC header fidelity for audit-grade email reconstruction.

Attachment Authentication

Attachment download URLs returned in API responses require the same bearer token used for other API calls — they are not pre-signed public URLs. Key operational notes:

• Attach the same Authorization: Bearer <token> header to attachment download requests.
• If your access token expires mid-extraction, attachment downloads will return 401 errors. Implement token refresh before starting large attachment batches.
• Attachment URLs do not appear to have a separate short expiry — they remain valid as long as the bearer token is valid — but this behaviour should be validated on your tenant, as it may differ across versions.
• Inline images are referenced by attachment ID in the message response and must be downloaded via the same attachment endpoint as file attachments.

API Error Codes

The following table documents common API error responses and their causes:

API Rate Limits

Puzzel does not publicly document specific numeric rate limits for the Case Management REST API. Third-party integration platforms that wrap the Puzzel API (such as Truto) explicitly handle pagination and rate limiting as a feature, confirming that limits exist but exact thresholds are not published.

Observed safe operating parameters (validate on your own tenant — limits may vary by account tier):

• Start at 1 request per second with a single worker thread
• Scale to 2–3 concurrent requests once baseline stability is confirmed
• Monitor response headers for any Retry-After or X-RateLimit-* values — if present, honour them exactly
• Implement exponential backoff with jitter on all 429 responses: initial retry after 2 seconds, doubling each subsequent attempt, with ±20% jitter to prevent thundering herd
• For 50,000 tickets at 1 req/sec for the list pass + 1 req/sec per ticket for content: minimum ~28 hours of API time, not counting attachment downloads. In practice, with 2 req/sec and parallel attachment fetching, expect 12–18 hours for extraction plus 4–8 hours for attachment download depending on total file volume.

Private Notes: An Underdocumented Edge Case

When adding a note to a ticket using the API, it is possible to flag it as public or private. When a note is marked private, it is not exposed when retrieving ticket content via a standard API channel.

This means: if your Puzzel instance uses private notes, those notes may be silently absent from your extraction. Validate this before you begin — see the verification procedure in the Authentication and Scoping section above.

API Extraction Pattern

A full extraction follows an N+1 pattern — one list pass to enumerate tickets, plus one call per ticket for content. There is no documented bulk content endpoint that returns full message threads and attachments in a single call. For 50,000 tickets, that is a minimum of 50,001 API calls before attachment downloads.

# Pseudocode: Puzzel Case Management API extraction flow
 
# 1. Authenticate and obtain access token
token = authenticate(client_id, client_secret)
 
# 2. Pull reference data first (lookup tables for transformation)
teams        = get_all_pages(token, "/teams")
categories   = get_all_pages(token, "/categories")
forms        = get_all_pages(token, "/forms")
tags         = get_all_pages(token, "/tags")
organisations = get_all_pages(token, "/organisations")
customers    = get_all_pages(token, "/customers")
 
# 3. List all tickets (paginated, filtered by date range)
all_tickets = []
page = 1
while True:
    response = list_tickets(token, date_from, date_to, page=page, per_page=100)
    all_tickets.extend(response["tickets"])
    if len(response["tickets"]) < 100:
        break  # Last page
    page += 1
 
# 4. For each ticket, fetch full content with retry logic
for ticket in all_tickets:
    if already_extracted(ticket["id"]):
        continue  # Idempotent: skip if previously completed
    ticket["messages"] = get_with_retry(token, f"/tickets/{ticket['id']}/messages")
    ticket["notes"]    = get_with_retry(token, f"/tickets/{ticket['id']}/notes")
    ticket["attachments"] = get_with_retry(token, f"/tickets/{ticket['id']}/attachments")
    save_to_local_db(ticket)
    rate_limit_wait(seconds=0.5)  # ~2 req/sec ceiling
 
# 5. Download attachments and inline images (separate worker)
for ticket in load_from_local_db():
    for attachment in ticket["attachments"]:
        if not already_downloaded(attachment["id"]):
            binary = download_with_retry(token, attachment["id"])
            path = save_to_storage(binary, attachment["filename"])
            update_local_db(attachment["id"], local_path=path)

Method 4: PCM Raw Data (BI and Audit)

Best for: Warehouse-style reporting, reconciliation, audit trails.

Puzzel offers PCM Raw Data as a separate database delivery with CM_-prefixed tables. This is not enabled by default — tables only contain PCM data if the PCM Raw Data product has been ordered and delivered. Customer-written SQL is out of scope for Puzzel support.

The documented raw-data schema includes:

Basic tables:

• cm_customers
• cm_channels
• cm_forms
• cm_organisations
• cm_teams
• cm_users

Ticket-related tables:

• cm_tickets
• cm_ticket_events
• cm_ticket_responses
• cm_reporting_ticket_states
• cm_form_field_answers

Reporting view:

• vwcm_ticket_performance — ticket-level reporting view

Ticket status codes:

Puzzel recommends filtering on update timestamps such as dte_updated when fetching Raw Data incrementally into your own database.

Raw Data Limitations

Raw Data does not solve content fidelity. The documented schema is state-, response-, and reporting-oriented. Message-body content — the exact HTML/TEXT of each email — is documented only through Message Content Info, Ticket Show, and Message Show via the REST API. Raw Data is a supplement for BI, delta auditing, and reconciliation, not the primary source for a migration out of Puzzel.

Additionally, there is no documented cm_attachments or cm_message_bodies table in the public Raw Data schema. Attachment binaries and full message content remain accessible only via the REST API.

Method 5: Customer Data Export (GDPR / DSAR)

Best for: Individual customer record exports, compliance requests.

Users with the appropriate permissions can go to Customers > Customers > Active, select the export button against a specific customer, and download a ZIP archive when the export is ready (the button changes to "Archive Download" when available).

When a customer's archive is downloaded, Puzzel records who initiated the download in the customer's audit trail, visible at the bottom of the individual customer page.

This per-customer export is designed for GDPR Data Subject Access Requests. For a full migration, it is impractical — you must trigger it individually for every customer record. There is no batch trigger mechanism.

Method 6: End-of-Contract SFTP Extraction

Best for: Complete data handoff when leaving the platform.

All data extraction is included within the licence cost, though any additional support required may be charged at Professional Service rates per day. Puzzel produces a full Exit Plan enabling the customer to take their data in a machine-readable format, with all other data deleted and purged in line with GDPR and UK Data Privacy considerations.

Puzzel's official end-of-contract process includes data extraction via SFTP or similar mechanisms, delivered as EML files and attachments. This is the most complete extraction option available but is only accessible during contract offboarding and is managed by Puzzel's team, not self-service.

Export Methods Compared

Data Portability Gaps: What You Cannot Export

Several categories of data and configuration cannot be exported through any available method:

• SLA rules and thresholds — must be manually documented and rebuilt
• Automated workflows and business rules — including inbound rules, event rules, and escalation logic
• Response templates / canned responses — no bulk export mechanism
• Agent permissions and role configurations — Puzzel-specific, must be recreated
• Queue routing logic — skill-based routing configurations do not map to export formats
• Dashboard and report builder configurations — remain in Puzzel

Note that Outbound Integrations, Event Rules, and Response Mappings features require explicit activation on a Puzzel Case Management instance before use — even API-adjacent features may not be enabled on your tenant by default.

Categories and Forms Mapping

Puzzel Case Management relies heavily on a structured Category and Form system to classify tickets and route them to the correct queue. If you are migrating to a platform with a flatter structure (such as tags or standard custom fields), you must flatten Puzzel's hierarchical categories before importing.

Large category choice sets paginate — the API now supports ?per_page=1000 for category choices as of the June 2025 release, but you must still handle the pagination metadata and iterate correctly. Do not assume a single request returns all choices for large category hierarchies.

Users vs. Agents

Differentiate between End Users (customers) and Agents (staff) during extraction. If you export all users into a single dataset and push them to a new system without role mapping, you risk granting administrative permissions to customers or locking agents out of their queues. Extract and map user roles explicitly before any import step.

The Attachment Extraction Challenge

Attachments and inline images are the most complex part of any helpdesk extraction. Puzzel stores attachments as separate entities linked to specific messages within a ticket and explicitly documents inline-image links in Ticket Show and Message Show API responses (since August 2024).

To extract them:

1. Parse the message payload: As you download ticket threads, scan the JSON response for attachment metadata — filename, size, content-type, and attachment ID.
2. Treat inline images as first-class items: Inline images are documented separately from file attachments. They are referenced by cid and attachment_id in the message body and must be downloaded via the same attachment endpoint. They are not cosmetic extras — they are part of the message content.
3. Authenticate all download requests: Attachment downloads require the same Authorization: Bearer <token> header as other API calls. URLs are not pre-signed or publicly accessible.
4. Download the binary: Make a separate authenticated GET request to the attachment endpoint using the attachment ID.
5. Store to cloud or local storage: Save files to S3 or equivalent secure storage. Record the new storage path in your local database against the attachment ID.
6. Remap URLs for the target system: When importing into your target system, parse the message HTML, locate old Puzzel image references, and replace them with the newly hosted URLs. This step is mandatory for inline images to render correctly in the target platform.

Retention, Deletion, and Limits That Bite Late

Check these before you start your export, not after:

• Retention periods: Tickets cannot be deleted while inside the configured retention period, but data is removed automatically once the automatic deletion period is reached. Automatic deletion can be counted from ticket creation date or resolve date and is processed by an overnight scheduled job.
• Attachment size limits: 50MB maximum incoming email size, 50MB maximum incoming attachment size, 10MB maximum outgoing email size. Storage is in the AWS Europe (Ireland) region.
• Merged tickets: There are known issues with merging tickets when an instance has a high number of tickets in the database. Verify that merged ticket content is fully accessible via the API — merged tickets may return partial data or 404 on the secondary ticket ID.

Common Edge Cases and Pitfalls

Email threading logic: Puzzel Case Management threads messages based on TID references in subject lines, where the ticket reference number must be greater than or equal to 100,000. If your target system uses different threading logic (such as In-Reply-To headers or conversation IDs), map this carefully before import.

Recipient fidelity: To, CC, BCC, and related email-address history live at the message level, not the ticket level. Use Message Content Info — not just Ticket Show — when audit-grade email header reconstruction is required.

Organisation-scoped API tokens: An Organisation-scoped token silently returns only tickets from that organisation. There is no error — you simply receive less data. For a complete export, always use Global scope and verify coverage by spot-checking ticket counts against the UI.

Scandinavian and non-ASCII characters: The May 2022 encoding fix addressed CSV exports. Validate API JSON responses independently — ensure your extraction script handles UTF-8 correctly and does not introduce encoding errors when writing to your local database.

Status mapping: Puzzel's status codes (0 through 7, covering Open, Pending, Resolved, Closed, Archived, Error, On-Hold, and Deleted) may not map 1:1 to your target platform's lifecycle model. Agree on status mapping before the first test import.

Child and parent tickets: Puzzel supports parent/child ticket relationships. Child tickets may not appear in default ticket list queries depending on filter settings. Confirm whether your list queries return child tickets or only parent tickets, and adjust accordingly.

Step-by-Step Full Data Export Plan

Step 1: Audit Your Data

Before writing a single line of extraction code, inventory what you have:

• Total ticket count across all statuses (Open, Pending, Resolved, Closed, Archived, Error, On-Hold, Deleted)
• Number of organisations and customers
• Attachment count and estimated total file size
• Custom categories, forms, and form field structures (including hierarchy depth)
• Whether private notes are used and whether they surface via your API token
• Current retention and automatic deletion settings
• Whether parent/child ticket relationships exist

Step 2: Set Up API Access

Go to Settings > Ticket Channels > API and create a new API channel with Global authentication level. Select Basic Token or OAuth Token based on your security requirements. Document credentials securely. Confirm on your tenant's Swagger UI which endpoints are available — not all documented endpoints may be enabled on all account tiers.

Step 3: Export Reference Data First

Use the REST API to pull organisations, teams, categories, forms, form fields, tags, customers, and custom field definitions. These serve as your lookup tables for transformation. Create user and organisation identities in your target system before migrating tickets — most helpdesk platforms reject ticket imports that reference non-existent assignees or requesters.

Step 4: Extract Tickets with Full Content via API

Use paginated ticket list endpoints filtered by date range and status. For each ticket, fetch messages (Ticket Show + Message Content Info for header fidelity), notes, and attachment metadata. Store raw JSON responses in a local relational database (PostgreSQL works well) rather than flat files — this makes querying, deduplication, and transformation substantially easier.

Step 5: Download Attachments and Inline Images

Run a separate worker script that reads your local database for undownloaded attachment IDs, fetches binaries with the same bearer token used for API calls, saves to cloud storage, and updates the local database with the new file path. Run this in parallel with ticket extraction where possible, but keep concurrency low to avoid rate limiting.

Step 6: Run a CSV Export for Cross-Validation

Use the UI-based CSV export as a validation check against your API extraction. Compare ticket counts by status, team assignment, and date range. The CSV is particularly useful for catching tickets in edge-case statuses (merged, error, deleted) that may not appear in default API queries.

Step 7: Execute the Delta Sync

By the time you finish extracting a large dataset, agents will have created and updated tickets. Before go-live, run a delta sync querying the API for tickets where updated_at exceeds the timestamp of your last extraction run. This ensures you do not miss changes that occurred during the extraction window.

Step 8: Validate Completeness

Check for:

• Missing message threads on older tickets
• Private notes absent from the extraction (compare against known test tickets with private notes)
• Attachment download failures (404 or 401 errors)
• Encoding issues with special characters in message bodies and subject lines
• Tickets in edge-case statuses (merged, archived, error, deleted)
• Correct user-role mapping (customers vs. agents)
• Child tickets missing from list queries
• Correct status code mapping to target platform equivalents

Security and Compliance Considerations

Puzzel is ISO 27001 certified (certified by DNV). Your extraction pipeline should meet equivalent standards:

• Encrypt data in transit: All Puzzel API communication uses TLS 1.2 or above.
• Encrypt data at rest: Store exported data with AES-256 encryption.
• Audit trail: Puzzel tracks who downloads customer archives in the audit trail. Maintain your own audit log of extraction activities including timestamps, ticket ID ranges, and operator identity.
• Data minimisation: Export only what is necessary for your specific migration or archival purpose.
• Secure deletion: After successful migration and validation, securely purge all intermediary export files.

When to Use Each Export Method

You're doing a quick data audit → Use the CSV Ticket Export. It is fast, self-service, and gives you enough metadata to understand your data landscape without API setup.

You need regular operational reports → Use the Report Builder with scheduled exports. Configure Include/Exclude filters to scope reports by team, category, or time period.

You're migrating to another platform → Use the REST API for complete extraction (for a practical example, see our Puzzel to Kayako migration guide). Supplement with CSV for validation. Consider the end-of-contract SFTP extraction if timing aligns with your contract end — it is the most complete option but requires Puzzel's involvement.

You need warehouse-style reporting or audit data → Use PCM Raw Data if you have ordered it. It is strong for BI and delta auditing but does not contain full message body content.

You're responding to a GDPR/DSAR request → Use the per-customer data export from the Customers page.

You're leaving Puzzel entirely → Engage Puzzel's offboarding team for the SFTP-based Exit Plan extraction. Request this early — exit plan delivery timelines vary and should be factored into your migration project plan.

Making the Right Call

Exporting data from Puzzel Case Management is technically straightforward once you understand that the CSV export covers metadata only and the REST API is required for complete data including message threads, notes, and attachments. The biggest operational risk is not the extraction itself — it is assuming the CSV gives you everything and discovering mid-migration that conversation history is missing.

Plan for the API path from day one. Set up authentication early, test against a small batch of 50–100 tickets, validate private note visibility against known test cases, confirm retention settings will not delete data mid-export, document your pagination parameters, implement exponential backoff with jitter on all retries, and authenticate attachment downloads with the same bearer token. For datasets of 50,000+ tickets, budget 12–18 hours of extraction time plus 4–8 hours for attachment downloads at a conservative 2 req/sec, and design your scripts to be idempotent so they can resume from any point after a failure.

The recurring trap is treating the first successful test extraction as complete. The hard part is the last 5 percent: private notes, inline images embedded in HTML bodies, child tickets, organisation context, merged ticket edge cases, and the delta of changes that land after your first test run.