CSV to Ada Migration: A Technical Guide

CSV to Ada Migration: A Technical Guide

Last updated: August 2025. Covers Ada Platform API v2.

Migrating data from CSV files into Ada means transforming flat, delimiter-separated records into JSON payloads that Ada's Platform APIs can accept. Ada has no native CSV import feature. Every record — whether it's a knowledge article, an end-user profile, or a tag — must be converted to JSON and pushed through the corresponding REST endpoint. The process is straightforward for small knowledge bases but gets complicated fast when you're dealing with encoding issues, multi-language content, field mapping ambiguity, and Ada's specific API constraints.

This guide covers the full pipeline: CSV preparation, field mapping, transformation scripts, API constraints, and the failure modes you'll hit in production.

What Data Can You Actually Import into Ada from CSV?

Before you build anything, understand what Ada's APIs accept and what they don't. This is where most CSV-to-Ada migration plans go wrong — teams assume they can load everything from their CSV exports into Ada, and that's not the case.

What you can import:

• Knowledge articles — via the Knowledge API (POST /api/v2/knowledge/bulk/articles/). Full read/write support, including bulk upsert.
• Knowledge sources — via the Knowledge API (POST /api/v2/knowledge/sources/). Every article must belong to a source.
• Tags — via the Knowledge API (POST /api/v2/knowledge/bulk/tags/). Labels for organizing articles. See the Tag Import section below for the full mapping and code example.
• End-user profiles — via the End Users API (POST /v2/end-users/). Name, email, language, metadata, and sensitive metadata fields.

What you cannot import:

• Historical conversations and messages. There is no endpoint that accepts historical conversation records. The Conversations API (POST /v2/conversations/) creates new, live conversations only — it does not accept historical data. If your CSV contains conversation transcripts, chat logs, or ticket histories, those records cannot be loaded into Ada.
• Bot configuration, playbooks, or custom instructions from CSV. These must be configured through the Ada dashboard or their respective single-object API endpoints.
• File attachments. Ada's attachment handling is for live conversation flows only, with a 50MB max and 7-day URL expiry.

Ada's API Constraints You Need to Know Before Writing Code

Ada's Platform APIs are REST-based with JSON payloads. Every CSV row must be transformed before it can be sent. Here are the hard limits that will shape your migration script:

Authentication

All Ada Platform API requests require a Bearer token in the Authorization header. To obtain a Platform API token:

1. Log in to your Ada dashboard.
2. Navigate to Settings → Integrations → Platform API.
3. Generate a new token. Store it securely — it is shown only once.

All requests use this header:

Authorization: Bearer YOUR_PLATFORM_API_TOKEN
Content-Type: application/json

A 401 Unauthorized response means the token is missing or malformed. A 403 Forbidden response means the token is valid but lacks permission for the requested endpoint — verify the token's scope in your Ada dashboard.

Knowledge API Limits

End Users API Limits

Data Export API Limits (for Extraction, Not Import)

These numbers matter. If your CSV contains 60,000 end-user records, you'll need at minimum a full day to push them through at the 60,000 req/day cap — and that assumes zero errors or retries. At 200,000 end users, plan for 3–4 days of continuous API calls.

API Error Code Reference

CSV Preparation: Encoding, Delimiters, and the Problems Nobody Warns You About

CSV is a plain-text format with no built-in encoding declaration. Unlike JSON (which assumes UTF-8) or XML (which has an encoding header), a CSV file carries zero metadata about how its bytes should be interpreted. This is the single biggest source of silent data corruption in CSV-based migrations.

Encoding Traps

• Excel's default CSV export uses Windows-1252, not UTF-8. Accented characters (é, ü, ñ), currency symbols (€, £), and non-Latin scripts will break when your Python script reads them as UTF-8.
• Excel's "CSV UTF-8" export adds a BOM (Byte Order Mark) — three invisible bytes (EF BB BF) at the start of the file. Ada's API expects clean JSON, and if those BOM bytes leak into your first field value, the API will reject the payload or — worse — silently store corrupted data.
• European locale CSVs use semicolons as delimiters because commas serve as decimal separators. If your source data was exported from a European-locale Excel instance, your parser will treat the entire row as a single column.

How to Fix It Before You Start

# Detect encoding
file -bi yourfile.csv
 
# Convert to UTF-8 without BOM
iconv -f WINDOWS-1252 -t UTF-8 input.csv > output.csv
 
# Strip BOM if present
awk '{if(NR==1)sub(/^\xef\xbb\xbf/,"");print}' output.csv > clean.csv

In Python, use encoding='utf-8-sig' when reading to automatically strip the BOM:

import csv
 
with open('input.csv', 'r', encoding='utf-8-sig') as f:
    reader = csv.DictReader(f)
    for row in reader:
        # row keys are now clean, BOM-free
        pass

For a deeper look at when CSVs work and when they fall apart in migrations, see our post on using CSVs for SaaS data migrations.

Mapping CSV Columns to Ada's Data Model

Ada's Knowledge API expects a specific JSON structure. Your CSV columns won't map 1:1 — you'll need a transformation layer.

Step 1: Create a Knowledge Source

Every article must belong to a source. Create the source before attempting any article upsert. If you reference a source_id that doesn't exist, the API returns 404.

import requests
 
ADA_BASE_URL = "https://yourinstance.ada.support/api/v2"
ADA_TOKEN = "your-platform-token"
 
headers = {
    "Authorization": f"Bearer {ADA_TOKEN}",
    "Content-Type": "application/json"
}
 
source_payload = {
    "id": "src-csv-import",
    "name": "CSV Import - Help Center",
    "description": "Knowledge articles imported from CSV export"
}
 
resp = requests.post(
    f"{ADA_BASE_URL}/knowledge/sources/",
    headers=headers,
    json=source_payload
)
 
if resp.status_code == 201:
    print(f"Source created: {resp.json()['id']}")
elif resp.status_code == 409:
    print("Source already exists — safe to proceed with article upsert")
else:
    raise Exception(f"Source creation failed: {resp.status_code} {resp.text}")

Step 2: Knowledge Article Mapping

A typical CSV for knowledge articles might look like:

id,title,body,category,language,url
kb-001,How to reset password,"Click Settings > Security > Reset...",account,en,https://help.example.com/reset
kb-002,Billing FAQ,"We accept Visa, Mastercard...",billing,en,https://help.example.com/billing

Ada's bulk upsert endpoint expects this JSON structure:

{
  "source_id": "src-csv-import",
  "articles": [
    {
      "id": "kb-001",
      "name": "How to reset password",
      "content": "Click Settings > Security > Reset...",
      "language": "en",
      "metadata": {
        "category": "account",
        "source_url": "https://help.example.com/reset"
      }
    }
  ]
}

Key mapping decisions:

• id must be unique and <= 160 characters. If your CSV uses numeric IDs, prefix them (e.g., kb-001) to avoid collisions with other sources.
• name maps to your title column. Max 255 characters.
• content is the article body. Max 100KB per article. If your CSV has articles exceeding this, you must split them before import.
• language must be one of the 9 supported languages. Articles in unsupported languages (e.g., Japanese, Korean, Polish) will be accepted by the API but will not generate accurate generative answers — Ada applies machine translation for unsupported languages, and quality varies significantly.
• Every article must belong to a source_id. Create the source first (see Step 1), then reference it in your bulk upsert.

Step 3: End-User Mapping

A CSV of end users might look like:

email,name,language,plan_type,account_id,user_token
jane@example.com,Jane Smith,en,enterprise,acct-1234,token-abc

The End Users API expects:

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "language": "en",
  "metadata": {
    "plan_type": "enterprise",
    "account_id": "acct-1234"
  },
  "sensitive_metadata": {
    "user_token": "token-abc"
  }
}

metadata vs. sensitive_metadata: Both accept arbitrary key-value pairs, but they differ in how Ada handles them:

• metadata is stored and accessible in the Ada dashboard, in conversation transcripts, and via API responses. Use it for non-sensitive CRM or account attributes (plan type, account tier, locale).
• sensitive_metadata is stored encrypted and is not surfaced in the Ada dashboard or conversation views. Use it for fields that should not be visible to Ada dashboard users — authentication tokens, PII, API keys, or any field your security policy requires to be restricted. The values are available to Generative Actions at runtime but are redacted in logs.

The Transformation Pipeline: CSV → JSON → Ada API

Here's a practical Python script skeleton for transforming CSV knowledge articles and pushing them to Ada's Knowledge API:

import csv
import json
import requests
import time
 
ADA_BASE_URL = "https://yourinstance.ada.support/api/v2"
ADA_TOKEN = "your-platform-token"
SOURCE_ID = "src-csv-import"
BATCH_SIZE = 50  # articles per request; keep well under 10MB
 
def read_csv(filepath):
    articles = []
    with open(filepath, 'r', encoding='utf-8-sig') as f:
        reader = csv.DictReader(f)
        for row in reader:
            article = {
                "id": row["id"].strip(),
                "name": row["title"].strip()[:255],
                "content": row["body"].strip(),
                "language": row.get("language", "en").strip(),
                "metadata": {
                    k: v for k, v in row.items()
                    if k not in ("id", "title", "body", "language")
                }
            }
            # Validate article size
            if len(json.dumps(article).encode('utf-8')) > 102400:
                print(f"WARNING: Article {article['id']} exceeds 100KB — skipping")
                continue
            articles.append(article)
    return articles
 
def bulk_upsert(articles, source_id):
    headers = {
        "Authorization": f"Bearer {ADA_TOKEN}",
        "Content-Type": "application/json"
    }
    for i in range(0, len(articles), BATCH_SIZE):
        batch = articles[i:i + BATCH_SIZE]
        payload = {
            "source_id": source_id,
            "articles": batch
        }
        # Check payload size
        payload_bytes = len(json.dumps(payload).encode('utf-8'))
        if payload_bytes > 10_000_000:
            print(f"Payload exceeds 10MB at batch {i}. Reduce BATCH_SIZE.")
            continue
 
        resp = requests.put(
            f"{ADA_BASE_URL}/knowledge/bulk/articles/",
            headers=headers,
            json=payload
        )
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            # Retry the same batch
            resp = requests.put(
                f"{ADA_BASE_URL}/knowledge/bulk/articles/",
                headers=headers,
                json=payload
            )
        if resp.status_code not in (200, 201):
            print(f"Error at batch {i}: {resp.status_code} {resp.text}")
        else:
            print(f"Upserted batch {i}–{i+len(batch)}")
        time.sleep(0.01)  # Stay under 200 req/sec
 
articles = read_csv("knowledge_articles.csv")
bulk_upsert(articles, SOURCE_ID)

This script handles the core path. In production, add:

• Exponential backoff with jitter for 429 responses (not just a flat Retry-After).
• Idempotency: Ada's bulk upsert is idempotent on the id field — re-running the script will update existing articles rather than create duplicates. This makes it safe to retry failed runs in full.
• A dry-run mode that validates all rows without sending API calls.
• Logging of every API response (status code, response body, batch index) for post-migration audit.

Importing Tags from CSV

Tags are listed in Ada's Knowledge API under POST /api/v2/knowledge/bulk/tags/. The CSV-to-tag mapping is simpler than articles but follows the same bulk structure.

A typical tags CSV:

tag_id,tag_name,tag_color
tag-001,billing,blue
tag-002,account,green
tag-003,technical,red

Ada's bulk tag upsert payload:

{
  "tags": [
    { "id": "tag-001", "name": "billing", "color": "blue" },
    { "id": "tag-002", "name": "account", "color": "green" },
    { "id": "tag-003", "name": "technical", "color": "red" }
  ]
}

Example tag import script:

def import_tags(filepath):
    tags = []
    with open(filepath, 'r', encoding='utf-8-sig') as f:
        reader = csv.DictReader(f)
        for row in reader:
            tags.append({
                "id": row["tag_id"].strip(),
                "name": row["tag_name"].strip(),
                "color": row.get("tag_color", "").strip() or None
            })
 
    headers = {
        "Authorization": f"Bearer {ADA_TOKEN}",
        "Content-Type": "application/json"
    }
    resp = requests.post(
        f"{ADA_BASE_URL}/knowledge/bulk/tags/",
        headers=headers,
        json={"tags": tags}
    )
    if resp.status_code not in (200, 201):
        print(f"Tag import failed: {resp.status_code} {resp.text}")
    else:
        print(f"Imported {len(tags)} tags")
 
import_tags("tags.csv")

Tags must be imported before articles if you plan to associate tags with articles at upsert time. If you're adding tags to existing articles post-import, the article update endpoint (PUT /api/v2/knowledge/articles/:id) accepts a tag_ids array.

Handling Knowledge Article Content from CSV

CSV is a poor format for rich text. If your knowledge base articles contain HTML, Markdown, or structured formatting, you'll hit these issues:

Commas and newlines inside content fields: A knowledge article body will almost certainly contain commas and line breaks. Your CSV must use proper quoting (double-quote delimiters with escaped inner quotes). Most CSV libraries handle this correctly, but manually edited CSVs often don't.

HTML entities: If your source system exported HTML content, it may contain entities like &, <, '. Decide whether to pass these through as-is (Ada will store them) or decode them before import.

Content size: Ada enforces a 100KB per-article limit. A single long FAQ document exported as one CSV row could exceed this. Check sizes programmatically and split oversized articles before attempting the upsert.

Content language: Ada's Knowledge API supports articles in 9 languages: English, Arabic, Chinese, Dutch, French, German, Italian, Portuguese, and Spanish. If your CSV includes articles in other languages, they'll be accepted by the API but may not generate accurate responses — Ada uses machine translation for unsupported languages, and quality varies.

Migrating End Users from CSV to Ada

End-user imports from CSV are conceptually simple but operationally tricky because of the 24-hour auto-deletion rule.

The workflow:

1. Parse your CSV, mapping each row to Ada's end-user schema (email, name, language, metadata, sensitive_metadata).
2. Call POST /v2/end-users/ for each user. There is no bulk endpoint — it's one request per user.
3. Respect the 300 req/min and 60,000 req/day limits.

Time estimate: 60,000 end users = 1 full day at max throughput. 200,000 end users = 3–4 days minimum. 500,000+ end users = over a week of continuous API calls.

The 24-hour auto-deletion constraint means you should not pre-load end users weeks before go-live. Time your end-user import to complete within 24 hours of when those users will start conversations. If you're using Ada's embed or SDK, end users get created automatically on first interaction — making a bulk pre-load unnecessary for many use cases.

Paginating GET Requests During Validation

After importing end users, validate by pulling samples via GET /v2/end-users/. This endpoint is paginated. Use limit and offset (or cursor-based pagination if supported by your Ada version) to walk through large result sets:

def fetch_end_users(limit=100):
    headers = {"Authorization": f"Bearer {ADA_TOKEN}"}
    offset = 0
    all_users = []
 
    while True:
        resp = requests.get(
            f"{ADA_BASE_URL.replace('/api/v2', '')}/v2/end-users/",
            headers=headers,
            params={"limit": limit, "offset": offset}
        )
        data = resp.json()
        users = data.get("results", [])
        all_users.extend(users)
        if not data.get("next"):
            break
        offset += limit
        time.sleep(0.1)  # Respect rate limits on GET requests
 
    return all_users

Compare the returned count against your CSV row count (minus known skips) to confirm completeness.

What About Conversation Data in Your CSV?

If you have conversation transcripts, chat logs, or ticket exports in CSV format, here's the definitive answer: you cannot import them into Ada.

Ada's Conversations API is designed for creating and managing live conversations. There is no historical import endpoint. The typical approach:

1. Archive to a data warehouse. Transform the CSV into a structured format (Parquet, BigQuery table, PostgreSQL) and keep it accessible for compliance and reference.
2. Build a lookup integration. If agents need to reference historical conversations during live Ada interactions, build a Generative Action that queries your archive and surfaces relevant history.
3. Accept the break. For reporting, treat the migration date as day zero. Historical metrics stay in the old system; new metrics start in Ada.

For a deeper walkthrough of conversation archival strategies, see our help desk data mapping guide.

Validation Checklist: Before and After the Import

If you are migrating a public-facing help center, you also need to plan for URL redirects and SEO preservation. For a complete look at those requirements, see our knowledge base migration checklist.

Pre-Import Validation

• Encoding confirmed as UTF-8 (no BOM, no Windows-1252 artifacts)
• Delimiter verified (comma vs. semicolon vs. tab)
• No article exceeds 100KB when serialized to JSON
• All article IDs are unique and <= 160 characters
• All article names are <= 255 characters
• Every article has a valid language value from the 9 supported languages
• Knowledge source created in Ada before bulk upsert (POST /api/v2/knowledge/sources/)
• Tags imported before articles if tag associations are needed at upsert time
• Total article count is under 50,000 (or your plan's custom limit)
• End-user email fields are valid and deduplicated
• sensitive_metadata fields identified and separated from standard metadata
• No conversation data in the import set (it will fail silently or be misinterpreted)

Post-Import Validation

• Article count in Ada matches CSV row count (minus skipped/errored rows)
• Spot-check 5–10 articles in Ada's dashboard for content accuracy, encoding, and formatting
• Test generative answers — ask the AI agent questions that should be answered by imported articles. Allow 5 minutes for indexing after the final upsert.
• Verify end-user profiles — pull a paginated sample via GET /v2/end-users/ and compare against CSV source
• Verify tags — pull tag list via GET /api/v2/knowledge/tags/ and compare against tags CSV
• Check rate limit usage in your logs to confirm no requests were silently dropped

Common Failure Modes

When CSV Is the Wrong Starting Point

CSV works for loading knowledge articles and end-user profiles into Ada — but it's the wrong tool in several scenarios:

• You need to preserve relationships between conversations, messages, and end users. CSVs flatten relational data. Use Ada's Data Export API (JSON) as your source instead.
• Your data contains rich formatting, embedded images, or attachments. CSV strips all of this. If your knowledge base has inline screenshots or downloadable PDFs, you need a different pipeline.
• You're migrating from another platform with an API. Pulling data via API and pushing to Ada's API directly (JSON-to-JSON) avoids the entire class of CSV encoding and parsing issues. It's more work to set up but dramatically more reliable at scale.
• Your dataset exceeds 50,000 articles. You'll need to coordinate with Ada's team for a higher limit, and at that volume, API-to-API is almost always faster and more reliable than CSV intermediation.

For a comparison of CSV vs. API vs. JSON export approaches, see Using CSVs for SaaS Data Migrations.

Keeping Data in Sync After the Initial Import

A migration isn't done when the initial load completes. If your knowledge base is maintained in an external system (a CMS, a wiki, a shared drive of CSVs), you need an ongoing sync strategy.

Ada's Knowledge API supports full upsert semantics — if an article with the same id already exists, it gets updated. This means you can re-run your CSV-to-Ada pipeline on a schedule to pick up changes. But there are caveats:

Deleted articles aren't handled by upsert. If you remove a row from your CSV, the corresponding Ada article remains. You need an explicit deletion step that diffs your CSV against Ada's article list and calls DELETE /api/v2/knowledge/articles/:id for removed articles. Here's a working implementation:

def sync_deletions(csv_filepath, source_id):
    """Remove Ada articles that no longer exist in the CSV."""
    # Build set of IDs from current CSV
    csv_ids = set()
    with open(csv_filepath, 'r', encoding='utf-8-sig') as f:
        reader = csv.DictReader(f)
        for row in reader:
            csv_ids.add(row["id"].strip())
 
    # Fetch all article IDs currently in Ada for this source
    headers = {"Authorization": f"Bearer {ADA_TOKEN}"}
    ada_ids = set()
    offset = 0
    limit = 1000
 
    while True:
        resp = requests.get(
            f"{ADA_BASE_URL}/knowledge/articles/",
            headers=headers,
            params={"source_id": source_id, "limit": limit, "offset": offset}
        )
        data = resp.json()
        articles = data.get("results", [])
        for article in articles:
            ada_ids.add(article["id"])
        if not data.get("next"):
            break
        offset += limit
        time.sleep(0.05)
 
    # Delete articles present in Ada but absent from CSV
    to_delete = ada_ids - csv_ids
    print(f"Articles to delete: {len(to_delete)}")
 
    for article_id in to_delete:
        resp = requests.delete(
            f"{ADA_BASE_URL}/knowledge/articles/{article_id}/",
            headers=headers
        )
        if resp.status_code == 204:
            print(f"Deleted: {article_id}")
        else:
            print(f"Failed to delete {article_id}: {resp.status_code} {resp.text}")
        time.sleep(0.01)  # Stay under rate limits
 
sync_deletions("knowledge_articles.csv", SOURCE_ID)

Additional sync caveats:

• Indexing latency applies to every update. Bulk-updated articles take up to 5 minutes to reflect in generative answers. If you're updating frequently, stagger updates to avoid serving stale content.
• Consider Ada's native integrations first. Ada has out-of-the-box integrations with Zendesk Guide, Salesforce Knowledge, Freshworks, Contentful, and others that handle sync automatically. If your knowledge lives in one of those systems, a direct integration is almost always preferable to a CSV pipeline.

Planning a Zero-Downtime Cutover

If you're migrating to Ada while keeping an existing support system running, the knowledge import from CSV can happen entirely in the background — it doesn't affect live operations. End-user imports need more careful timing due to the 24-hour auto-deletion rule.

The real downtime risk comes from the cutover: the moment you switch live traffic to Ada. Plan for a brief parallel-run period where both systems are active. For detailed strategies on managing this, see our guide on zero-downtime help desk migration.

When to Seek Additional Help

A CSV-to-Ada knowledge import with under 5,000 articles and clean, well-encoded data is a reasonable DIY project for a team with Python experience. Budget a day for scripting, a day for testing, and a half-day for validation.

The complexity increases significantly when:

• Your CSV has encoding problems or inconsistent formatting from multiple export sources — each source may require a separate transformation layer
• You're importing both knowledge articles and end users and need coordinated timing to avoid the 24-hour auto-deletion window
• Your article count approaches or exceeds the 50,000 cap and requires coordination with Ada's team
• You need an ongoing sync pipeline (not just a one-time load), including the deletion-diffing logic
• You have conversation data that needs archival alongside the Ada migration, requiring a separate data warehouse pipeline

ClonePartner has handled 1,500+ migrations including complex CSV-to-platform data loads with encoding normalization, field mapping, and API orchestration. If the scope is bigger than a weekend project, we can get it done in days.