DevelopersCSV Import APIs

CSV Import APIs

CSV Import APIs enable you to upload CSV files with intelligent column mapping, description generation, and automated processing.

Overview

The CSV import workflow:

  1. Upload CSV - Upload file and start import workflow
  2. Column Analysis - AI analyzes and describes columns
  3. User Review - Review and edit column mappings/descriptions
  4. Import - Process and import data
  5. Monitor - Track import progress

Upload CSV

Upload a CSV file and start the import workflow with streaming.

POST /api/lists/csv/upload 
Content-Type: multipart/form-data

Request

curl -X POST https://chordian-core.chordian.ai/api/lists/csv/upload \
  -F "file=@companies.csv"

Successful Response (200 OK)

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Review CSV Import

Continue CSV import after user review with edited column descriptions.

POST /api/lists/csv/review/{thread_id}

Request Body

{
  "listName": "Tech Companies Q1 2025",
  "listDescription": "Technology companies for Q1 outreach",
  "description": "Tech companies for Q1 outreach",
  "category": "Sales Prospects",
  "column_descriptions": [
    {
      "column_name": "Company Name",
      "column_id": "company_name",
      "description": "Official registered company name"
    },
    {
      "column_name": "Website",
      "column_id": "website",
      "description": "Primary company website URL"
    },
    {
      "column_name": "Employee Count",
      "column_id": "employee_count",
      "description": "Approximate number of employees"
    }
  ]
}
FieldTypeRequiredDescription
listNamestringCustom list name
listDescriptionstringList description
descriptionstringAlternative description field
categorystringWorkflow category
column_descriptionsarrayColumn descriptions with user edits

Column Description Object

FieldTypeRequiredDescription
column_namestringDisplay column name (user editable)
column_idstringOriginal CSV column name (for mapping)
descriptionstringColumn description (AI-generated or user-edited)

Successful Response (200 OK)

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get CSV Import Status

Get the current status of a CSV import.

GET /api/lists/csv/status/{thread_id}

Successful Response (200 OK)

"string"

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Status Values

StatusDescription
analyzingAnalyzing CSV structure
ready_for_reviewWaiting for user review
importingImporting data
processingProcessing imported data
completedImport completed successfully
errorImport failed with errors

Restore CSV Import State

Restore CSV import state from database using list ID.

GET /api/lists/csv/restore/{list_id}

Successful Response (200 OK)

{
  "list_id": "string",
  "status": "restored",
  "criteria": [],
  "total_target": 25,
  "table_structure": {
    "columns": [
      {
        "id": "string",
        "header": "string",
        "type": "string",
        "width": 180,
        "required": false,
        "columnType": "string",
        "dataType": "string"
      }
    ],
    "rows": [
      {
        "id": "string",
        "cells": {
          "additionalProp1": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          },
          "additionalProp2": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          },
          "additionalProp3": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "pending",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          }
        },
        "step_source": "string",
        "metadata": {
          "additionalProp1": {}
        }
      }
    ],
    "total_target": 25,
    "current_count": 0
  },
  "title": "string",
  "description": "string",
  "thread_id": "string",
  "listType": "string",
  "supervisor_started": false
}

Validation Error (422)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Complete Import Flow Example

import requests
import json
import time
 
BASE_URL = "https://chordian-core.chordian.ai"
 
# 1. Upload CSV
with open('companies.csv', 'rb') as file:
    files = {'file': file}
    response = requests.post(
        f"{BASE_URL}/api/lists/csv/upload",
        files=files
    )
    
    # Parse streaming response
    data = response.json()
    thread_id = data.get('thread_id')
    columns = data.get('columns', [])
 
# 2. Review and edit columns (user input)
edited_columns = [
    {
        "column_name": col['column_name'],
        "column_id": col.get('column_id'),
        "description": col['description']  # User can edit this
    }
    for col in columns
]
 
# 3. Continue import
review_response = requests.post(
    f"{BASE_URL}/api/lists/csv/review/{thread_id}",
    json={
        "listName": "My Custom List",
        "listDescription": "Description of my list",
        "category": "Sales",
        "column_descriptions": edited_columns
    }
)
list_id = review_response.json().get('list_id')
 
# 4. Monitor progress
def check_status():
    status_response = requests.get(
        f"{BASE_URL}/api/lists/csv/status/{thread_id}"
    )
    status = status_response.json()
    
    if status.get('status') == 'completed':
        print('Import complete!', status)
    elif status.get('status') == 'error':
        print('Import failed:', status.get('errors'))
    else:
        print(f"Progress: {status.get('progress', {}).get('percentage', 0)}%")
        time.sleep(2)
        check_status()  # Poll again
 
check_status()

CSV Format Requirements

? Info: Supported Formats: CSV files with comma, semicolon, or tab delimiters are supported.

Best Practices

  1. Header Row - First row should contain column names
  2. Consistent Delimiters - Use consistent delimiters throughout
  3. UTF-8 Encoding - Use UTF-8 encoding for special characters
  4. Clean Data - Remove extra whitespace and formatting
  5. File Size - Keep files under 50MB for optimal performance

Example CSV

Company Name,Website,Industry,Employee Count
Acme Corp,https://acme.com,Technology,150
TechStart Inc,https://techstart.io,SaaS,45
Global Solutions,https://globalsolutions.com,Consulting,500

Error Handling

Common Errors

ErrorCauseSolution
Invalid file formatFile is not CSVUpload a valid CSV file
Empty fileCSV has no dataEnsure file contains data rows
Too many columnsExceeds column limitReduce number of columns
Parsing errorMalformed CSVCheck CSV formatting

Error Response

{
  "status": "error",
  "errors": [
    {
      "row": 15,
      "column": "Website",
      "message": "Invalid URL format",
      "value": "not-a-url"
    }
  ]
}

Best Practices

  1. Validate CSV - Validate CSV format before uploading
  2. Review Columns - Always review AI-generated column descriptions
  3. Clear Names - Use clear, descriptive column names
  4. Monitor Progress - Poll status endpoint during import
  5. Handle Errors - Implement error handling for failed imports

Next Steps