Teamwork CRM to Kommo Migration: A Technical Guide

Migrating from Teamwork CRM to Kommo is a data-model translation, not a file conversion. Teamwork CRM separates your deals into distinct Lead pipelines and Opportunity pipelines — a lead must be "qualified" before it graduates to an opportunity. Kommo uses a single Lead entity that moves through pipeline stages from first touch to won/lost. That structural mismatch is the root cause of broken pipeline stages, orphaned activities, and lost conversion history during this migration.

Critical naming conflict: In Teamwork CRM, a "Lead" is a pre-qualification deal object that sits in its own pipeline. In Kommo, a "Lead" is the primary deal record — closer to what Teamwork calls an "Opportunity." If you map Teamwork CRM leads to Kommo leads without also mapping Teamwork CRM opportunities to Kommo leads, you lose half your deal history. Every mapping decision in this guide addresses this explicitly. (support.teamwork.com)

Kommo has no native Teamwork CRM import. You must extract from Teamwork via its REST API or CSV export, transform the data, and load it into Kommo via CSV import or the Kommo v4 REST API.

Why This Migration Is Harder Than It Looks

Three structural problems make this migration non-trivial:

1. Dual pipeline collapse. Teamwork CRM manages leads and opportunities in separate sections with independent pipelines and stages. Kommo has a single pipeline per sales process. You need to decide: merge both into one Kommo pipeline, or create two (one for qualification, one for closing). Either choice requires stage remapping.

2. Activity history doesn't travel via CSV. Kommo's built-in CSV import handles leads, contacts, and companies. But activity history — calls, emails, notes, meetings — logged against Teamwork CRM deals cannot be imported via CSV. That data requires the Kommo API. This is a common failure point across all CRM-to-Kommo migrations.

3. Lead-per-user caps on Kommo. Kommo enforces active lead limits per user per plan: Base includes 2,500 active leads per user, Advanced provides 5,000, and Enterprise goes up to 10,000. If you're migrating a large Teamwork CRM database, calculate your active deal count against these caps before you start loading data. Importing 8,000 active deals on a Base plan will hit plan limits.

Teamwork CRM vs. Kommo: Data Model Mapping

Kommo has structural constraints you need to know before mapping:

• Accounts can have up to 10 pipelines, each with up to 100 stages. (developers.kommo.com)
• Incoming Leads, Closed – Won, and Closed – Lost are system stages — they can be renamed but not replaced.
• A Kommo lead can link to multiple contacts but only one company. A contact can belong to only one company.
• Do not import historical Teamwork deals into Kommo's Incoming Leads stage unless you want them treated as unprocessed inbound records. Kommo's Incoming Leads section is an unsorted inbox for channel-created records. Migrated deals should land directly in a named pipeline stage.

The Pipeline Merge Decision

This is the single most consequential decision in the migration. In Teamwork CRM, a lead that gets qualified converts into an opportunity — it moves from the Leads section to the Opportunities section, potentially entering a different pipeline with different stages. Kommo has no concept of "qualifying" a lead into a separate entity type. A lead stays a lead. It just moves to a different stage.

Option A: Single merged pipeline. Combine Teamwork CRM's lead stages and opportunity stages into one sequential Kommo pipeline: New → 1st Touch → Qualified → Proposal → Negotiation → Won/Lost. Simpler to operate, but you lose the clear separation between pre-qualification and post-qualification. In Kommo's funnel reporting and user performance dashboards, all stages appear in one funnel — you cannot filter to show only post-qualification conversion rates without building manual segments. This affects forecasting accuracy if your team tracks qualification rate separately from close rate.

Option B: Two parallel pipelines. Create a "Qualification" pipeline and a "Sales" pipeline in Kommo. Import Teamwork leads into the first, opportunities into the second. Preserves your reporting structure, but introduces operational overhead: reps must manually move leads between pipelines, Kommo's Digital Pipeline automations apply per-pipeline (so you duplicate automation rules across both), and cross-pipeline deal reporting is not supported natively. Dashboards and the built-in forecast view do not aggregate across pipelines.

Most teams choose Option A for simplicity, with a tag (e.g., qualified) to mark the qualification boundary. The tag enables manual filtering even though native reporting doesn't segment it. Preserve the original Teamwork record type and source ID in custom fields either way — you'll need them for reconciliation and reruns.

Reversibility: Option A is significantly harder to undo. Once you merge pipelines and teams start working in the unified structure, splitting them back apart means reassigning every deal, rebuilding automations, and updating all saved filters. Choose deliberately.

Extracting Data from Teamwork CRM

API vs. CSV Export

Teamwork CRM supports both paths. CSV export lets you export custom slices of leads, opportunities, people, activities, and products from list views based on current columns, filters, and the selected pipeline. Important limitations: deleted records are not included in standard exports, and site-level exports use default columns rather than your custom column sets. (support.teamwork.com)

For a full-fidelity migration — especially one that needs delta syncs or repeatable runs — the Teamwork CRM REST API (v2) is the better extraction path. Authenticate using Bearer token or Basic Auth with an API key generated under Settings → Personal → API Keys. (support.teamwork.com)

Primary extraction endpoints:

• GET /crm/api/v2/companies.json — all companies
• GET /crm/api/v2/contacts.json — all contacts
• GET /crm/api/v2/deals.json — all deals (leads + opportunities)
• GET /crm/api/v2/activities.json — all activities
• GET /crm/api/v2/pipelines.json — pipeline and stage definitions
• GET /crm/api/v2/custom-fields.json — custom field definitions

Extraction Order

Extract parent objects before child objects to maintain relational IDs for the mapping phase:

1. Users (Owners)
2. Pipelines and Stages
3. Custom Field Definitions
4. Companies
5. Contacts
6. Deals (Leads + Opportunities)
7. Activities and Notes
8. Files/Attachments

Pagination and Rate Limits

Teamwork CRM's API uses offset-based pagination. The default page size is 20 records. The response includes a meta.page object with pageOffset, pageSize, and count (total records). The API enforces 150 requests per minute globally — all users and integrations share this pool. Exceeding it returns HTTP 429 with X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers so you can pace your extraction script.

import requests
import time
 
BASE_URL = "https://yoursite.teamwork.com/crm/api/v2"
API_KEY = "your-api-key"
headers = {"Authorization": f"Bearer {API_KEY}"}
 
def extract_all(endpoint, page_size=50):
    records = []
    page = 1
    while True:
        resp = requests.get(
            f"{BASE_URL}/{endpoint}.json",
            headers=headers,
            params={"page[number]": page, "page[size]": page_size}
        )
        if resp.status_code == 429:
            wait = int(resp.headers.get("X-Rate-Limit-Reset", 60))
            time.sleep(wait)
            continue
        resp.raise_for_status()
        data = resp.json()
        records.extend(data.get(endpoint, []))
        meta = data.get("meta", {}).get("page", {})
        if (meta.get("pageOffset", 0) + meta.get("pageSize", 0)) >= meta.get("count", 0):
            break
        page += 1
        time.sleep(0.5)  # stay under 150 req/min
    return records

Distinguishing Leads from Opportunities

Teamwork CRM's API returns all deals through the /deals.json endpoint. Each deal has a pipeline association that tells you whether it's a lead or an opportunity. When extracting, tag each record with its source type — you'll need this during transformation to route it to the correct Kommo pipeline stage.

The Transformation Layer

Between extraction and loading, a transformation step must handle:

1. Deal type routing. Read each Teamwork CRM deal's type (lead vs. opportunity) and assign it to the correct Kommo pipeline and stage.
2. Stage mapping. Map Teamwork CRM stage names to Kommo status IDs. Fetch your Kommo pipeline statuses via GET /api/v4/leads/pipelines to get the exact numeric IDs.
3. User mapping. Teamwork CRM user IDs ≠ Kommo user IDs. Build a lookup table mapping Teamwork ownerId values to Kommo responsible_user_id values.
4. Contact deduplication. Teamwork may have the same person listed as both a contact and a deal-level record. Kommo's dedup logic under CSV import checks email first, then phone. Under the API, the complex endpoint checks for an existing contact matching by email or phone — if found, it links the existing contact rather than creating a duplicate; if multiple matches exist, it links the first match returned. This behavior is predictable on clean data and dangerous on dirty data. Normalize before loading, not after.
5. Custom field mapping. Build a mapping dictionary from Teamwork field IDs to Kommo field IDs. Kommo references custom fields by integer ID, not by name.
6. Currency normalization. If Teamwork CRM stores deal values in multiple currencies, map them to Kommo's monetary field format (value + currency code).
7. Timestamp conversion. Kommo requires Unix timestamps (integers), not ISO-8601 strings. Your script must convert Teamwork's 2023-10-31T14:30:00Z format to 1698762600.
8. External IDs. Add Teamwork source IDs (tw_company_id, tw_contact_id, tw_deal_id) as custom fields on every Kommo record. Without stable source IDs, reruns become guesswork and rollback is nearly impossible.

A minimal external-ID worksheet looks like this:

tw_record_type,tw_record_id,kommo_pipeline,kommo_stage,company_key,contact_key
lead,18421,Inbound,New,acme.com,jane@acme.com
opportunity,9912,Sales,Proposal,acme.com,jane@acme.com

That pattern enables deterministic reruns, makes rollback possible, and lets anyone trace a Kommo record back to its Teamwork source.

Custom Field Type Mapping

Teamwork CRM custom fields don't always map cleanly to Kommo:

Create all custom fields in Kommo before running the import via POST /api/v4/leads/custom_fields. This is an admin-only endpoint. The response returns the field IDs you'll need for the data load.

Loading Data into Kommo

Two Loading Paths

Path 1: CSV Import (simpler, limited). Kommo supports import from .xls, .xlsx, .ods, or .csv files. Hard constraints: single-sheet, no empty rows, max 2 MB and 10,000 rows per file. Kommo can ingest one spreadsheet containing leads, contacts, and companies and create the links during import. It can also create new custom fields and save mapping templates during the import flow. (support.kommo.com)

CSV import cannot carry:

• Activity/note history
• File attachments
• Pipeline stage history
• Tasks

Path 2: API Import (full fidelity, more work). Kommo's v4 REST API supports creating leads, contacts, companies, notes, tasks, and custom fields programmatically. For a complete migration that preserves activity history, this is the only viable path.

Kommo API Authentication

Kommo uses OAuth 2.0 for public integrations and long-lived tokens for private integrations. For a one-time migration, a private integration with a long-lived token is the fastest path. Create it under Settings → Integrations → Create Integration → Private.

If using OAuth 2.0, access tokens expire after 24 hours. Your migration script must include logic to refresh the token via /oauth2/access_token, or the script will fail midway through a large load.

Kommo Automation Trigger Warning

Critical: When you load records via the Kommo API, Kommo's Digital Pipeline automations fire on record creation. If you have automations configured — webhook notifications, auto-assignments, status-change emails — they will trigger for every imported lead and contact. Before starting the production load, disable all Digital Pipeline automations and re-enable them after the import is validated. Failure to do this has caused teams to spam thousands of contacts with onboarding emails during migration loads.

Loading Order and the Complex Lead Endpoint

Load companies first, then contacts, then deals. This ensures deduplication and linking are predictable when you load Teamwork records.

Kommo offers a batch endpoint designed for importing leads with linked contacts and companies in a single call:

POST https://{subdomain}.kommo.com/api/v4/leads/complex

This endpoint creates leads, contacts, and companies in one request and links them automatically. It supports duplicate control — Kommo checks for existing contacts by phone or email. The constraints are tighter than regular endpoints: no more than 50 leads per request and only one related contact and one related company per lead in that call. (developers.kommo.com)

import requests
 
SUBDOMAIN = "yourcompany"
API_KEY = "your-long-lived-token"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
 
payload = [
    {
        "name": "Acme Corp Website Redesign",
        "price": 15000,
        "pipeline_id": 12345,
        "status_id": 67890,
        "responsible_user_id": 111,
        "created_at": 1698762600,  # Unix timestamp, not ISO-8601
        "custom_fields_values": [
            {"field_id": 222, "values": [{"value": "Inbound"}]}
        ],
        "_embedded": {
            "contacts": [
                {
                    "first_name": "Jane",
                    "last_name": "Smith",
                    "custom_fields_values": [
                        {"field_code": "EMAIL", "values": [{"value": "jane@acme.com", "enum_code": "WORK"}]},
                        {"field_code": "PHONE", "values": [{"value": "+15551234567", "enum_code": "WORK"}]}
                    ]
                }
            ],
            "companies": [
                {"name": "Acme Corp"}
            ]
        }
    }
]
 
resp = requests.post(
    f"https://{SUBDOMAIN}.kommo.com/api/v4/leads/complex",
    headers=headers,
    json=payload
)

For standard batch operations (contacts, companies, or leads without inline entity creation), the regular endpoints accept up to 250 entities per POST request.

Kommo API Error Response Structure

When a batch POST partially fails, Kommo returns HTTP 200 with a mixed response body: successful entities appear in _embedded with their assigned IDs, and failed entities appear in a separate errors array with an error code and description per record. Your retry logic must parse this structure — do not treat HTTP 200 as full success. Re-queue only the failed records from the errors array, not the entire batch.

Throughput Estimates

At a sustained 5 req/sec using the complex endpoint (50 leads per request), you can load approximately 900,000 lead-records per hour in raw throughput terms. In practice, transformation overhead, network latency, and retry handling reduce this. A realistic load rate for a well-optimized script is 15,000–25,000 leads per hour. For a 10,000-deal migration with full note history (assuming ~5 notes per deal), expect 3–5 hours of API load time after transformation is complete.

Migrating Activity History, Notes, and Files

This is where most DIY migrations fall short. Teamwork CRM tracks activities (calls, emails, meetings, notes) against deals with timestamps, responsible users, outcomes, and free-text descriptions.

Notes and Activities

Kommo stores activity history as notes attached to leads:

POST https://{subdomain}.kommo.com/api/v4/leads/{lead_id}/notes

The note_type field controls how the note renders. Map Teamwork activities like this:

• Call activities → call_in or call_out note type
• Email activities → common note with [Email] prefix
• Meeting activities → common note with [Meeting] prefix
• General notes → common note type

Do not dump every Teamwork activity into Kommo tasks. Kommo tasks are live work items with a required responsible user and deadline. They're a good target for open/future activities and a terrible target for historical logs. The rule: future or open Teamwork activities → Kommo tasks; past or completed activities → Kommo notes.

A simple historical note format that works in practice:

[Teamwork activity]
Type: Meeting
Status: Completed
When: 2026-07-14 15:00 UTC
Owner: Sarah Ng
Description: Demo completed, pricing follow-up due next week

File Attachments

File migration is the most bandwidth-intensive part. Teamwork provides temporary download URLs via the API. Kommo handles files through its Files API.

The process:

1. Request file metadata from Teamwork.
2. Download the binary file to your local server or middleware.
3. Upload to Kommo via multipart/form-data to /api/v4/files.
4. Kommo returns a file_uuid.
5. Create a Note on the target Lead/Contact using the file_uuid to link the uploaded document.

Do not pass Teamwork's temporary download URLs directly into Kommo. Those URLs expire, and you'll end up with dead links across your CRM.

Cutover Plan and Delta Sync

A typical Teamwork CRM to Kommo migration for 5,000–20,000 deals follows this timeline:

Total: 7–12 days for a mid-size migration. Smaller migrations under 1,000 deals can finish in a weekend. Kommo does not offer a dedicated sandbox environment — use a separate Kommo trial account for test loads, and ensure it is on the same plan tier as production to expose any plan-limit constraints before going live.

Delta Sync

If your team keeps working in Teamwork CRM during the migration, you need a delta sync pass:

1. Initial Load. Run the full migration. Record the exact timestamp when extraction began.
2. Validation. Verify data integrity in Kommo — pipeline totals, custom field mappings, note attachments.
3. Delta Extraction. Query Teamwork's API for records modified after the initial extraction timestamp using the updatedAfter filter. Teamwork also supports webhooks that POST on event triggers — the webhook payload includes the record type, record ID, event type, and a timestamp — which can capture late changes between your test load and final cutover. (support.teamwork.com)
4. Delta Load. Transform and push only the new/updated records into Kommo. Since you mapped Teamwork IDs to Kommo IDs during the initial load, use PATCH for existing records and POST for new ones.
5. Cutover. Revoke write access to Teamwork CRM. Confirm all reporting and automations are functional in Kommo. Re-enable Digital Pipeline automations. Rebuild any pipeline automations that existed in Teamwork.

What to Validate Before Go-Live

At minimum, validate: entity counts (total companies, contacts, leads by pipeline), open vs. closed deal counts, pipeline and stage distribution, owner distribution, total open value by pipeline, and spot samples for notes, files, linked companies, and contacts. Use Kommo import tags or source ID custom fields to isolate migrated records via filtered API reads. Validate via GET /api/v4/leads with explicit filters rather than eyeballing the UI — the UI can paginate and cache in ways that make totals misleading.

Rollback Procedure

If your test load or production load produces unacceptable data quality, you need a defined cleanup path before you load more records.

For API-loaded records: Use the Teamwork source ID custom fields to identify migrated records. Query Kommo via GET /api/v4/leads filtered by the custom field value (e.g., tw_deal_id is populated), then batch-delete using DELETE /api/v4/leads with the returned IDs. Kommo's delete endpoint accepts up to 250 IDs per request. Apply the same pattern to contacts and companies loaded during the migration.

For CSV-imported records: Kommo does not provide a native bulk-undo for CSV imports. You must identify the imported records (by import date, tag, or source ID field) and delete them via the API. This is another reason to tag every migrated record during load — it makes cleanup deterministic.

Partial rollback: If only a subset of records is corrupted (e.g., a custom field mapped incorrectly), use PATCH /api/v4/leads to correct field values in bulk rather than deleting and reloading. Batch PATCH accepts up to 250 records per request.

Record the Kommo IDs of every successfully created entity during load. If you don't capture these during the load run, you'll need to re-derive them from source ID lookups — which works only if you preserved source IDs on every record.

What You Lose in This Migration

Be explicit with stakeholders about what doesn't transfer cleanly:

• Pipeline stage history. Kommo records the current stage. It does not import a full stage-transition timeline from another system. You can preserve transition history as notes, but native reporting won't reflect it.
• Activity engagement metrics. Email open rates, click tracking from Teamwork CRM integrations — these don't migrate.
• Automation rules. Teamwork CRM pipeline automations and triggers must be rebuilt manually in Kommo's Digital Pipeline.
• Products/line items. Kommo handles products through Catalogs, which has a different data model. Only one product list per account. Multi-currency setups need redesign, not copy-paste.
• Cross-pipeline reporting (if you choose Option B). Kommo's built-in dashboards and forecast views do not aggregate across pipelines. If you split qualification and closing into two pipelines, you lose unified funnel reporting unless you build it externally.

Common Failure Modes

1. Not checking Kommo plan limits before import. Loading 6,000 active leads on a Base plan (2,500 limit per user) will fail. Calculate your needs first.
2. Case-sensitive field name mismatches on CSV import. Kommo requires exact field name matching including capitalization. One typo and the column is silently skipped.
3. Repeated 429s causing IP block. Kommo blocks IPs that repeatedly violate the 7 req/sec limit. Use a queue with backoff, not tight loops.
4. Kommo automations firing on imported records. Digital Pipeline automations trigger on record creation via the API. Disable all automations before the production load and re-enable afterward. Teams that skip this have sent thousands of automated emails to historical contacts during migration.
5. Forgetting to link contacts to leads. If you import contacts and leads separately via CSV, they arrive unlinked. Use the complex lead endpoint (API) or enable "Create new contacts" during CSV import.
6. Importing into Incoming Leads. Kommo's "Incoming Leads" section acts as an unsorted inbox for channel-created records. Migrated deals should go directly to a pipeline stage.
7. Skipping external IDs. Without Teamwork source IDs on every Kommo record, you cannot safely rerun, reconcile, or roll back after a failed test load.
8. Turning every historical activity into a Kommo task. Tasks require a responsible user and deadline. Historical activities belong in notes.
9. Treating HTTP 200 as full success on batch API calls. Kommo returns HTTP 200 even when individual records in a batch fail. Parse the errors array in the response body and re-queue failed records explicitly.

When to DIY vs. When to Get Help

DIY is viable if:

• You have fewer than 1,000 deals
• Activity history isn't critical
• You're comfortable with Python/Node and REST APIs
• You can tolerate a weekend of parallel downtime

Get expert help if:

• You have 5,000+ deals with activity history that must be preserved
• You need zero-downtime cutover with delta sync
• Custom field mapping is complex (10+ custom fields with enum values)
• You're running multiple pipelines in Teamwork CRM with cross-pipeline deal movement

At ClonePartner, we've done this exact migration pattern. Our scripts handle extraction with pagination and rate-limit pacing, transformation with dedup and field normalization, and loading with retry logic. Typical turnaround is 5–10 business days. For another example of a Teamwork model-translation migration, see our Teamwork CRM to Close guide. For broader migration planning, our CRM Data Migration Checklist covers the full pre-migration audit process.

The Real Risk Is the Model, Not the Bytes

Teamwork CRM to Kommo is very doable, but only if you respect the data model change. The technical execution — OAuth tokens, rate limits, Unix timestamps — is standard API engineering. The actual risk is translating Teamwork's dual-funnel architecture into Kommo's unified Lead model without losing pipeline context, activity history, or the ability to reconcile and rerun.

Map your pipelines carefully. Decide between Option A and Option B before you write a line of transformation code — the choice affects automation architecture, reporting, and rollback complexity. Preserve source IDs on every record. Batch your API requests to avoid throttling. Disable Digital Pipeline automations before your production load. Parse Kommo's batch responses for partial failures. And use Kommo's _embedded architecture to build relationships on the first pass rather than patching them in afterward.

If you treat this as a CSV drag-and-drop rather than a structural translation, you will spend months cleaning up the aftermath.