---
title: "Capsule to Lightfield Migration: A Technical Guide"
slug: capsule-to-lightfield-migration-a-technical-guide
date: 2026-08-03
author: Nachi
categories: [Migration Guide, CRM]
excerpt: "Technical guide to migrating from Capsule CRM to Lightfield. Covers API constraints, object mapping, CSV vs. API methods, and edge cases that break most migrations."
tldr: "Capsule to Lightfield migration requires splitting Party objects into Accounts and Contacts, translating milestones to stages, and handling entry history via API — CSV works for simple moves, API-to-API for full fidelity."
canonical: https://clonepartner.com/blog/capsule-to-lightfield-migration-a-technical-guide/
---

# Capsule to Lightfield Migration: A Technical Guide


# Capsule to Lightfield Migration: A Technical Guide

Migrating from Capsule CRM to Lightfield is a data-model translation problem, not a data copy. Capsule stores contacts and organizations as a single **Party** entity with tags, custom fields, and separate Entry objects for activity history. Lightfield is an **agent-assisted CRM** built around **Accounts**, **Contacts**, and **Opportunities** — where each object type supports both structured field values and unstructured interaction context (emails, transcripts, meeting notes) indexed for AI retrieval. "Agent-native" means the platform exposes an AI layer that reads from and writes to those objects automatically, maintaining records from connected email and calendar without manual input.

There is no native one-click migration path between these two systems. Your viable options are: **(1)** CSV export from Capsule plus Lightfield's agentic CSV import, which handles most contact and opportunity data, or **(2)** a custom API-to-API pipeline using Capsule's REST API v2 for extraction and Lightfield's REST API for loading, which gives you full control over relationship mapping, entry history, and attachments. Most real-world migrations use a hybrid of both.

This guide covers the API constraints on both sides, object-by-object mapping with field-type translation, every viable migration method with trade-offs, deduplication strategy, failure recovery, and the edge cases that cause silent data loss.

## Why Teams Move from Capsule to Lightfield

Capsule is a lightweight, structured CRM built for small teams: contact management, sales pipelines, task tracking, and basic project boards. It works well when simplicity matters and manual data entry is acceptable.

Lightfield takes a different approach. Instead of requiring manual logging, it captures customer interactions from email, calendar, and calls, then builds and maintains CRM records through an AI layer. The practical consequences:

- **Data hygiene fatigue:** Capsule requires manual logging of notes, calls, and emails. Lightfield auto-captures interactions and keeps fields current without human input.
- **Unstructured context over structured fields:** For founder-led sales and relationship-driven GTM, the full text of conversations is often more valuable than dropdown selections. Lightfield stores complete conversation history and makes it queryable by the AI layer.
- **Consolidation:** Teams running Capsule alongside a separate call recorder, email sequencer, and enrichment tool can reduce tool count by moving to Lightfield's unified platform.
- **AI-assisted workflows:** Lightfield's agent layer can draft follow-ups, suggest pipeline changes from buying signals, and auto-enrich records — capabilities Capsule doesn't offer natively.

## Capsule CRM Data Model: What You're Extracting

Before mapping anything, catalog exactly what lives in Capsule. The API v2 exposes these core resources ([developer.capsulecrm.com](https://developer.capsulecrm.com/v2/operations/Party)):

| Capsule Object | Description | API Endpoint |
|---|---|---|
| **Party** | People and Organizations (unified entity) | `/api/v2/parties` |
| **Opportunity** | Sales deals linked to a pipeline + milestone | `/api/v2/opportunities` |
| **Project** | Post-sale or operational work (API: `kases`) | `/api/v2/kases` |
| **Entry** | Notes, emails, call logs — the activity history | `/api/v2/entries` |
| **Task** | To-dos linked to parties, opportunities, or projects | `/api/v2/tasks` |
| **Pipeline / Milestone** | Sales stage definitions | `/api/v2/pipelines`, `/api/v2/milestones` |
| **Tag** | Freeform labels on any object | `/api/v2/tags` |
| **Custom Field** | User-defined fields on parties, opportunities, projects | `/api/v2/fields` |
| **Track** | Workflow automations (sequences of tasks) | `/api/v2/tracks` |

Two details matter for extraction planning:

1. **Entries are separate objects.** Notes, emails, and activity logs are not embedded in parties or opportunities — they're linked via entity IDs and must be fetched per-record or by date range. The entries list endpoint maxes out at **50 items per page**, tighter than the 100-per-page limit on other endpoints ([developer.capsulecrm.com](https://developer.capsulecrm.com/v2/models/entry)).
2. **Tags and custom fields require the `embed` parameter.** A standard `GET /api/v2/parties` call does not include tags or custom field values. You must explicitly request `?embed=tags,fields` to get them.

> [!WARNING]
> Capsule's full account export (Account Settings → Export Data) generates a ZIP with three CSV files: Contacts, Opportunities, and Projects. **File attachments are excluded entirely** — they must be downloaded individually via the API. The export link expires after 12 hours. Opening the CSV in Excel can truncate long note-history fields at 32,000 characters, silently destroying old deal context.

## Lightfield Data Model: What You're Loading Into

Lightfield's data model is built around three core CRM object types plus custom objects:

| Lightfield Object | Description |
|---|---|
| **Account** | Companies/organizations |
| **Contact** | Individual people, linked to accounts |
| **Opportunity** | Deals with configurable stages |
| **Custom Object** | User-defined entities (e.g., projects, contracts) |

The architectural difference: Lightfield stores both **structured attributes** (fields with values) and **unstructured context** (full email threads, meeting transcripts, call recordings) in a unified index. Each field can be configured with a natural language definition and optionally set to **AI Fill** — meaning Lightfield's agent populates and updates it automatically from captured interactions. This is what makes field schema design during migration consequential: fields you configure for AI Fill don't need manual population, which changes which historical data is worth migrating.

Lightfield's API is in **public beta** and provides REST endpoints with Python, TypeScript, and Go SDKs, a CLI, and MCP access. It supports creating accounts, contacts, opportunities, and custom objects programmatically, and offers **idempotency keys** on create operations — critical for retry safety during bulk loads ([docs.lightfield.app](https://docs.lightfield.app/using-the-api/idempotency/)).

**Important:** Lightfield's list data is served from a search index that may lag recent changes. After writing records, validate with the record-specific retrieve endpoint, not list searches.

## Object-by-Object Mapping: Capsule → Lightfield

### Parties → Accounts + Contacts

Capsule's **Party** is a polymorphic entity — it can be a `person` or an `organisation`, determined by the `type` field. Lightfield separates these into two distinct objects.

| Capsule Party Field | Lightfield Target | Notes |
|---|---|---|
| `type: "organisation"` → name, about | **Account** → name, description | Direct map |
| `type: "person"` → firstName, lastName, jobTitle | **Contact** → name, title | Direct map |
| `organisation` (nested on person) | Contact → Account relationship | Link via organisation name/ID |
| `emailAddresses []` | Contact → email | Capsule allows multiple; Lightfield stores multiple |
| `phoneNumbers []` | Contact → phone | Same handling |
| `addresses []` | Account or Contact → address | Org addresses → Account, person addresses → Contact |
| `tags []` | Labels or custom field | Map tags to labels or a multi-select field |
| Custom fields via `fields []` | Custom attributes | Create matching fields in Lightfield first |

**Edge case — orphaned contacts:** Capsule allows people to exist without an organization link. You can create a placeholder "Unaffiliated" account, leave them unlinked and let Lightfield's enrichment resolve the association, or clean the data pre-migration.

**Edge case — phantom companies:** A Capsule person can reference an organization *name* that doesn't exist as its own Party record. You'll get orphaned company names on contacts with no matching Account in Lightfield. Pre-scan for this before loading.

### Opportunities → Opportunities

| Capsule Opportunity Field | Lightfield Target | Notes |
|---|---|---|
| `name` | Opportunity → `$name` | Direct |
| `value`, `currency` | Opportunity → value | Check currency handling |
| `milestone.name` | Opportunity → `$stage` | Must pre-create stages in Lightfield |
| `probability` | Custom field | Lightfield has no native probability field |
| `expectedCloseDate` | Opportunity → close date | Direct map |
| `party` (linked contact/org) | Opportunity → `$account` + Contact | `$account` is required |
| `lostReason` | Custom field | Create if needed |

In Lightfield, **`$name`, `$stage`, and `$account` are required** on opportunities. Accounts must be created before deals can be loaded ([docs.lightfield.app](https://docs.lightfield.app/api/cli/resources/opportunity/methods/create/)).

Capsule supports multiple pipelines, each with its own milestones. Map each pipeline's stages separately in Lightfield's data model configuration.

### Custom Field Type Mapping

Capsule and Lightfield support different field type sets. This table is required reading before you configure Lightfield's schema:

| Capsule Field Type | Lightfield Attribute Type | Notes |
|---|---|---|
| Text | Text | Direct map |
| Number | Number | Direct map |
| Date | Date | Direct map; verify UTC handling (see Edge Cases) |
| Boolean (checkbox) | Boolean | Direct map |
| List (dropdown) | Select | Pre-create all option values in Lightfield before import; importing a value that doesn't exist in the select list will fail or silently drop the value |
| Multi-select tag | Multi-select | Create options first; tag-to-multi-select migration requires pre-cleaning to normalize variant spellings |

**Do not map Capsule text fields to Lightfield select fields unless you've pre-cleaned the data.** Freeform text in a field that Lightfield expects to be a controlled vocabulary will fail validation or create garbage options.

### Projects → Custom Objects (or Redesign)

Capsule Projects (the API still uses the legacy `kases` endpoint) have **no direct equivalent** in Lightfield's default schema. Your options:

1. **Create a custom object** in Lightfield for Projects with relevant fields.
2. **Flatten into account/opportunity notes and tasks** if projects are lightweight delivery wrappers.
3. **Keep projects in a dedicated PM tool** if they're operationally critical.

> [!WARNING]
> If Capsule Projects are part of your delivery, billing, or client onboarding workflow, this is a process redesign, not a data copy. Do not schedule a migration cutover until you've mapped the business function, not just the data object.

### Entries (Notes/History) → Notes or Transcripts

Capsule Entries include notes, manually logged emails, and call logs — all with timestamps, author info, and optional attachments.

Lightfield's unstructured context is designed to be captured *live* from connected email and calendar, not bulk-imported as historical text. The Email API is built around synced mailbox retrieval plus sending/drafting from connected Google or Microsoft accounts — that is not the same as bulk-loading arbitrary historical CRM emails ([docs.lightfield.app](https://docs.lightfield.app/using-the-api/emails-and-attachments/)).

Your options:

- **Import via API as notes:** Create note-type records linked to the relevant contacts and accounts. Historical Capsule emails typically land better as notes than as native Lightfield email objects. Always pass the original Capsule `created_at` timestamp explicitly — see the Edge Cases section on timestamp overwrite.
- **Upload as meeting transcripts:** For call logs with substantial content, Lightfield supports uploading transcripts via the API, which the agent can index and reason over.
- **Accept the cutoff:** Connect Lightfield to email and calendar going forward, treat Capsule as the archive for pre-migration history. This is the right call if your team rarely references notes older than a few months.

### Tasks → Tasks

Capsule tasks include due dates, categories, assignments, and completion status. Lightfield tasks require **`$title`, `$status`, and `$assignedTo`**, with each task belonging to an account. Map directly, but translate Capsule's task categories to Lightfield labels and build your user crosswalk before loading tasks.

### Tracks → Rebuild, Not Migrate

Capsule **Tracks** are predefined sequences of tasks applied to parties or opportunities. These cannot be migrated as data — they must be **rebuilt** in Lightfield as Automations or Workflows. Lightfield's automation system uses natural-language instructions rather than rigid task templates, so this is a redesign, not a port.

## API Constraints on Both Sides

### Capsule API Limits

Capsule's REST API v2 enforces **4,000 requests per hour** per bearer token ([developer.capsulecrm.com](https://developer.capsulecrm.com/v2/overview/handling-api-responses)). At 100 records per page, you can theoretically extract 400,000 party records per hour — but if you also fetch entries per party, that number drops sharply. A 10,000-contact database with entry history can consume a significant portion of your hourly quota on entry extraction alone.

Key constraints:

- **Max 100 items per page** for most endpoints; entries max at **50 per page**
- Page-based pagination with `page` and `perPage` parameters
- The `since` parameter on list endpoints enables incremental extraction for delta syncs
- Deleted records have separate endpoints for tracking removals

Extraction with rate-limit handling:

```python
import requests
import time

CAPSULE_TOKEN = "your_capsule_bearer_token"
BASE_URL = "https://api.capsulecrm.com/api/v2"
headers = {
    "Authorization": f"Bearer {CAPSULE_TOKEN}",
    "Accept": "application/json"
}

def extract_all_parties():
    parties = []
    page = 1
    while True:
        resp = requests.get(
            f"{BASE_URL}/parties",
            headers=headers,
            params={"page": page, "perPage": 100, "embed": "tags,fields"}
        )
        if resp.status_code == 429:
            reset_time = int(resp.headers.get("X-RateLimit-Reset", 60))
            time.sleep(reset_time)
            continue
        resp.raise_for_status()
        data = resp.json()
        batch = data.get("parties", [])
        if not batch:
            break
        parties.extend(batch)
        page += 1
        time.sleep(1)  # Stay well under rate limits
    return parties
```

### Lightfield API Limits

Lightfield enforces **25 requests per second** for reads, writes, and searches per organization. Both APIs return `429` status codes when limits are exceeded; Lightfield includes a `Retry-After` header ([docs.lightfield.app](https://docs.lightfield.app/getting-started/http-quickstart/)).

The API is in **public beta** — pin the version header in requests, test in a staging workspace, and don't build migration scripts against undocumented response shapes.

Lightfield supports **idempotency keys** on create operations. Use deterministic keys derived from source system IDs so retries stay safe. Here is a complete example showing Account creation followed by a linked Contact, and then an Opportunity — the required load order:

```json
// Step 1: Create Account
POST /accounts
{
  "idempotencyKey": "capsule-org-1042",
  "fields": {
    "$name": "ACME Corporation",
    "description": "Enterprise software buyer"
  }
}
// Response: { "id": "acc_7xk2p9" }

// Step 2: Create Contact linked to Account
POST /contacts
{
  "idempotencyKey": "capsule-person-3891",
  "fields": {
    "$name": "Jane Smith",
    "title": "VP of Engineering",
    "email": "jane@acme.com"
  },
  "relationships": {
    "$account": "acc_7xk2p9"
  }
}
// Response: { "id": "con_4mn8q1" }

// Step 3: Create Opportunity — $name, $stage, and $account are all required
POST /opportunities
{
  "idempotencyKey": "capsule-opportunity-4812",
  "fields": {
    "$name": "ACME Renewal 2026",
    "$stage": "Negotiation"
  },
  "relationships": {
    "$account": "acc_7xk2p9"
  }
}
```

If Lightfield returns a `409 Conflict` on an idempotency key collision, the original record was already created — retrieve it by the source ID from your local ID map rather than retrying the create.

## Migration Methods: CSV vs. API vs. Hybrid

### Method 1: CSV Export + Lightfield Agentic Import

**Best for:** Teams under 10,000 records with straightforward data (contacts, opportunities, basic custom fields).

Export via Account Settings → Export Data, then upload the CSVs to Lightfield's agentic import.

**Limitations:**

- Capsule's full export bundles note/email history into a single text column per record — concatenated text, not structured entries. Parsing fidelity varies.
- File attachments are excluded from the export.
- Relationship integrity depends on matching names or IDs across the CSVs.
- Capsule's report exports cap at **20,000 rows** and exclude custom fields and tags.

**Throughput caution:** Lightfield's migration page states the agent processes roughly 15,000 records per hour, while a separate Lightfield blog post claims up to 90,000 records per hour. These figures are likely measuring different things (simple contacts vs. full records with relationships). Test with your actual dataset before committing to a cutover window.

### Method 2: API-to-API Custom Pipeline

**Best for:** Teams with more than 10,000 records, complex custom fields, important entry/note history, or file attachments.

Extract from Capsule via REST API v2, transform into an intermediate JSON format, then load into Lightfield via REST API or SDK. Store Capsule ID → Lightfield ID mappings in a local database (SQLite or Redis) as you go — you will need these for relationship linking and for delta sync.

### Method 3: Hybrid (CSV + API Enrichment)

**Best for:** Most real-world migrations.

Use CSV export for the bulk of contacts and opportunities, then use the Capsule API to extract entries, attachments, and relationship metadata the CSV doesn't capture. Load the CSVs via Lightfield's agentic import, then enrich records via the Lightfield API. This minimizes API calls against Capsule's rate limit while still preserving historical context.

## Step-by-Step Migration Execution

### Step 1: Audit Your Capsule Data

Before touching code or exports, catalog what you have:

- Total party count (people + organizations)
- Total opportunities and which pipelines they belong to
- Number of projects and their board/stage structure
- Custom fields and tags in active use (some will be legacy)
- Approximate volume of entries and notes
- File attachments that need to move
- Full user roster and ownership mapping

### Step 2: Configure Lightfield's Data Model

Before importing anything:

1. Create custom fields on Accounts, Contacts, and Opportunities matching your Capsule custom fields. Use the field-type mapping table above to pick correct attribute types.
2. For List/Select fields, pre-create all option values before import. A value not present in the option list will fail silently or be dropped.
3. Set up opportunity stages to mirror your Capsule pipeline milestones.
4. If migrating Projects, create a custom object type.
5. Configure fields you want Lightfield to auto-populate with **AI Fill** — for example, "last contacted date" or "deal status summary" can be AI-maintained rather than migrated.
6. Inspect Lightfield's definitions endpoints to confirm field keys and select-option IDs before writing data.

> [!TIP]
> Don't replicate your Capsule schema verbatim. Fields that required manual entry in Capsule can be AI-maintained in Lightfield. Use the migration as an opportunity to simplify rather than recreate every stale field.

### Step 3: Map Users

Extract all active and inactive Users from Capsule. Map their Capsule IDs to Lightfield User/Member IDs. If a Capsule user no longer exists in Lightfield, designate a fallback "System Admin" user to inherit their historical records. Lightfield tasks require `$assignedTo`, so this crosswalk must exist before you load tasks or any owned records.

### Step 4: Extract Data from Capsule

**CSV path:** Export via Account Settings → Export Data.

**API path:** Run extraction scripts for parties (with `embed=tags,fields`), opportunities, entries, and tasks. Store as JSON. Budget time around Capsule's 4,000 requests/hour ceiling — entry extraction is where most of the rate limit gets consumed.

For **REST hooks** (Capsule's event-based alternative to polling): hooks require a registered OAuth application and account-admin management. OAuth registration is separate from the bearer token used for API reads — you must create an OAuth app in Capsule's developer settings, complete the authorization flow, and store the resulting access token. REST hooks are capped at **20 subscriptions per account** ([developer.capsulecrm.com](https://developer.capsulecrm.com/v2/overview/avoid-polling-with-rest-hooks)). For most migrations, polling with the `since` parameter is simpler and sufficient.

### Step 5: Transform and Clean

**Splitting parties:**
- Filter `type: "organisation"` → create as Lightfield Accounts.
- Filter `type: "person"` → create as Lightfield Contacts, linking to Accounts via the `organisation` field.

**Deduplication strategy:**
Before inserting, query Lightfield for existing records that match on email address (for contacts) or normalized company name (for accounts). The recommended approach:

1. For each Capsule person, extract their primary email address.
2. Query Lightfield's search endpoint: `GET /contacts?filter=email:{email}`.
3. If a match is returned, update the existing record rather than creating a new one.
4. For organizations, normalize names (lowercase, strip punctuation) and match against existing accounts.
5. Flag ambiguous matches (same name, different email domain) for manual review rather than auto-merging.

If Lightfield's agentic import is handling the initial load, it performs its own deduplication against existing records — but the matching logic is not publicly documented. For large imports, validate post-load record counts against expected totals.

**Tag cleanup:**
Run a frequency analysis on all tags before migration. Tags used on fewer than 5 records are typically legacy noise — discard or consolidate before loading. Tags used on more than 50 records are candidates for dedicated Lightfield fields rather than labels.

**Other transforms:**
- Map Capsule milestones to Lightfield opportunity stages.
- Convert Capsule List custom field values to Lightfield select option IDs (requires the option IDs from Step 2).
- Build your full ID crosswalk: Capsule party ID → Lightfield account/contact ID.

### Step 6: Load into Lightfield

**Order is mandatory for referential integrity.** Load in this sequence:

1. **Accounts** first (from Capsule organisations)
2. **Contacts** second (from Capsule persons), linking to accounts
3. **Opportunities** third, linking to accounts and contacts
4. **Custom objects** (projects) fourth
5. **Notes/entries** last, linked to the correct records
6. **Attachments** separately — download from Capsule's API, upload to Lightfield's file manager, link to the correct records

Use idempotency keys on every write formatted as `capsule-{objecttype}-{id}` (e.g., `capsule-org-1042`). Cache your ID mappings in a local SQLite or Redis database — you will need them for relationship linking in steps 2 through 6.

### Step 7: Failure Recovery

Partial failures during bulk loads are normal. Do not assume a failed batch means lost data. Recovery procedure:

1. **Check your ID mapping store.** Records with a Lightfield ID were created successfully. Records without one were not.
2. **Re-run the load for failed records only.** Idempotency keys prevent double-creation — submitting a previously successful create again returns the original record, not a duplicate.
3. **For `409 Conflict` responses:** the record already exists. Retrieve by your ID mapping.
4. **For `422 Unprocessable Entity` responses:** the payload has a validation error (most commonly, a select option value that doesn't exist, a required field missing, or a relationship referencing a record that wasn't loaded yet). Fix the source data and retry.
5. **For `500` responses:** these are server errors and are safe to retry after a backoff delay.

Track a load manifest: for each batch, record the count of records sent, records confirmed created (via retrieve), and records failed. Do not proceed to the next object type until the current type's failure count is zero or explicitly accepted.

### Step 8: Run Delta Sync

If your team continues using Capsule during the migration, capture changes made after the initial extraction:

- **Poll with `since` parameters:** Query Capsule's list endpoints using the `since` parameter plus deleted-record endpoints. This is the simpler option and works for most migrations.
- **REST hooks:** Better for timely deltas but require OAuth app registration (see Step 4 notes). Capped at 20 subscriptions per account.

Run delta sync continuously until the final cutover. On cutover day, run the last sync, verify record counts match between systems, and switch the team.

### Step 9: Validate and Connect Live Sources

- Spot-check 5–10% of records across all object types.
- Verify opportunity values and stages match source data.
- Confirm contact-to-account linkages.
- Validate custom field values transferred correctly, paying specific attention to select fields.
- Use Lightfield's **retrieve** endpoints for validation, not list searches:

```python
# Correct: validate via retrieve
GET /accounts/{lightfield_account_id}

# Incorrect for post-write validation: list results may lag
GET /accounts?filter=name:ACME
```

- Connect Lightfield to your team's email (Gmail/Microsoft 365) and calendar to activate live interaction capture.

> [!WARNING]
> Lightfield can auto-create accounts and contacts from connected email and calendar activity. Decide before onboarding whether auto-creation should stay off, stay selective, or be allowed only after the baseline import is validated. Enabling it prematurely creates duplicate risk against your freshly loaded records.

## Edge Cases That Break Migrations

**Historical timestamps.** When you insert a historical note via API, the target CRM often stamps `created_at` as the moment of the API call, destroying your timeline. You must explicitly pass the original Capsule `created_at` timestamp in the request payload. If the Lightfield API does not permit overriding the creation date on a given object type, prepend the original date to the note body in the format `[Originally logged: 2022-03-14]`.

**Tag bloat.** Capsule accounts accumulate thousands of obsolete tags over years. Run frequency analysis before migration. Tags on fewer than 5 records are candidates for discard. Tags on more than 50 records are candidates for dedicated fields. Importing thousands of unmanaged tags into Lightfield degrades the user experience for your sales team immediately.

**Entry attachments at scale.** Each attachment download via Capsule's API (`GET /api/v2/entries/{entryId}/attachments/{attachmentId}`) counts against your 4,000 requests/hour rate limit. For accounts with thousands of attached files, attachment extraction alone can consume hours of quota. Run attachment downloads in a separate time window from record extraction, or use a dedicated API token if your Capsule plan supports multiple tokens.

**Lightfield record limits by plan tier.** Verify your Lightfield plan's record cap before importing. If your Capsule database exceeds the cap, imports will fail or require an upgrade. Lightfield does not publicly document these limits per tier — confirm with Lightfield support before beginning a large migration.

**Custom field type mismatches.** Covered in the field-type mapping table above. The most common failure: a Capsule List field imported as free text, then mapped to a Lightfield select field that doesn't have the incoming values pre-configured. The record loads without the field value, no error is returned, and the data is silently dropped.

**Timezone handling.** Capsule stores timestamps in UTC. Lightfield also uses UTC internally. No conversion is needed, but verify your transformation layer is not applying local timezone offsets — a common bug in Python datetime handling when `datetime.now()` is used instead of `datetime.utcnow()` or timezone-aware objects.

**Concatenated history in CSV exports.** Capsule's full export stuffs all note and email history into a single text column. Parsing this reliably requires handling variable formatting, embedded timestamps, and multiline content. Do not assume clean delimiters.

**Select option pre-population.** Any Lightfield select or multi-select field must have its option values created before import. This is the single most common source of silent data loss in field-level imports. Audit every Capsule List field, extract all unique values, create them as options in the corresponding Lightfield field, and then run the import.

**GDPR/CCPA considerations.** Transferring personal data between CRM systems constitutes processing under GDPR (Article 4(2)) and may require a documented legitimate interest or updated data processing records. For EU-regulated teams: confirm that Lightfield's data residency matches your current Capsule data region before migrating. For US teams subject to CCPA: verify that the migration doesn't expand the categories of processors with access to California resident data without updated disclosures.

**Projects are the biggest structural gap.** If a project is a lightweight delivery wrapper, flatten it into account or opportunity notes and tasks. If it's operationally important — billing triggers, client onboarding gates, delivery milestones — keep it in another system or delay the move until you've redesigned the workflow. Map business function, not just data objects.

## When Not to Migrate to Lightfield

Lightfield is not the right target for every Capsule user:

- **If you need mature project management:** Capsule's Projects with boards and stages offer basic project tracking. Lightfield has no native project boards — you would need custom objects and manual workflows.
- **If your team is large with deep integrations:** Lightfield targets early-stage teams. If you're running 50+ reps on Capsule with integrations into accounting, helpdesk, and marketing tools, verify Lightfield's integration ecosystem covers your stack before committing.
- **If API stability is critical right now:** Lightfield's API is in public beta. For teams building automation on top of the CRM API, expect iteration and potential breaking changes. Pin your API version and monitor the changelog.

## What This Migration Actually Takes

For a typical Capsule account (2,000–10,000 contacts, a few hundred opportunities, moderate note history):

| Phase | Estimated Time |
|---|---|
| Data audit and schema design | 2–4 hours |
| Lightfield data model setup | 1–2 hours |
| CSV export + cleanup | 1–2 hours |
| Import via Lightfield agent | Under 1 hour |
| Validation and spot-checks | 2–3 hours |
| Email/calendar connection + onboarding | 1–2 hours |
| **Total (CSV path)** | **~1–2 days** |

API-to-API migrations with full entry history and attachments add 1–3 days depending on volume and custom field complexity. Migrations where Projects require redesign as custom objects add additional time proportional to workflow complexity — budget separately and treat it as a process project, not a data task.

For general migration planning patterns, see our [10-point CRM data migration checklist](https://clonepartner.com/blog/blog/the-ultimate-crm-data-migration-checklist-a-10-point-plan-for-a-zero-loss-transition/).

## Migration Checklist

Use this as a pre-cutover verification checklist:

- [ ] Capsule custom fields cataloged, field types documented, Lightfield attribute types confirmed
- [ ] All select/multi-select option values pre-created in Lightfield
- [ ] Opportunity stages created in Lightfield matching all Capsule pipeline milestones
- [ ] User ID crosswalk complete (Capsule user ID → Lightfield member ID)
- [ ] Load order confirmed: Accounts → Contacts → Opportunities → Custom Objects → Notes → Attachments
- [ ] Idempotency keys applied to every create operation
- [ ] ID mapping store (SQLite/Redis) operational and persisted
- [ ] Load manifest tracking counts per batch
- [ ] Failure recovery procedure tested on a sample batch
- [ ] Post-load validation using retrieve endpoints, not list searches
- [ ] Record count reconciliation: Capsule total vs. Lightfield total per object type
- [ ] Lightfield email/calendar connection held until post-import validation complete
- [ ] Auto-creation setting confirmed (off or selective) before team onboarding
- [ ] GDPR/CCPA review complete if applicable
- [ ] Delta sync running and verified before cutover date

## Getting This Right

A Capsule to Lightfield migration succeeds when you treat it as schema translation plus context preservation. Extract from Capsule with the API, not just the ZIP. Rebuild organisations and people as accounts and contacts in the correct load order. Define your stage mapping and pre-populate select options before loading opportunities. Convert historical entry data intentionally — choose notes, transcripts, or a clean cutoff based on how frequently your team references old context. Resolve the Projects gap before scheduling cutover.

The critical failure modes are silent, not loud: select fields that drop values because options weren't pre-created, notes that lose their timestamps because `created_at` wasn't passed explicitly, contacts that arrive without account links because phantom companies weren't pre-scanned, and duplicates created by Lightfield's auto-enrichment firing before the baseline import was validated. Every one of these is preventable with the steps above.

> Planning a Capsule to Lightfield migration with active reps, entry history, or no room for downtime? Our team builds custom migration scripts that handle the full data model translation — parties to accounts/contacts, entry history, attachments, custom fields, and pipeline mapping. Zero downtime, verified accuracy.
>
> [Talk to us](https://cal.com/clonepartner/meet?duration=30)

## Frequently asked questions

### Can I migrate from Capsule CRM to Lightfield using CSV exports?

Only for low-complexity datasets. Capsule's full export generates CSVs for Contacts, Opportunities, and Projects, but file attachments are excluded, note history is concatenated into a single text column, and relationship integrity depends on name matching. If you need entry history, attachments, or deterministic validation, use the API.

### What are the API rate limits for Capsule and Lightfield?

Capsule allows 4,000 API requests per hour per bearer token with a max of 100 records per page (50 for entries). Lightfield enforces 25 requests per second for reads, writes, and searches per organization. Both return 429 status codes when limits are exceeded.

### How do Capsule Parties map to Lightfield objects?

Capsule uses a single Party object for both people and organizations, distinguished by a type field. Lightfield separates these into Account (for organizations) and Contact (for people). During migration, split parties by type and link contacts to accounts using the organisation relationship from Capsule's person records.

### Can I migrate Capsule Projects to Lightfield?

Not as a clean one-to-one copy. Capsule exposes Projects via the kases API endpoint, but Lightfield has no native project object. Your options are creating a custom object in Lightfield, flattening projects into notes and tasks, or keeping them in a dedicated PM tool.

### How do I avoid duplicates in Lightfield during import?

Use deterministic idempotency keys (e.g., capsule-party-{id}) on every create operation so retries are safe. Validate writes with Lightfield's record-specific retrieve endpoints, not list searches, because list results may lag recent changes.