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:
- Upload CSV - Upload file and start import workflow
- Column Analysis - AI analyzes and describes columns
- User Review - Review and edit column mappings/descriptions
- Import - Process and import data
- 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-dataRequest
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"
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
listName | string | ❌ | Custom list name |
listDescription | string | ❌ | List description |
description | string | ❌ | Alternative description field |
category | string | ❌ | Workflow category |
column_descriptions | array | ✅ | Column descriptions with user edits |
Column Description Object
| Field | Type | Required | Description |
|---|---|---|---|
column_name | string | ✅ | Display column name (user editable) |
column_id | string | ❌ | Original CSV column name (for mapping) |
description | string | ✅ | Column 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
| Status | Description |
|---|---|
analyzing | Analyzing CSV structure |
ready_for_review | Waiting for user review |
importing | Importing data |
processing | Processing imported data |
completed | Import completed successfully |
error | Import 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
- Header Row - First row should contain column names
- Consistent Delimiters - Use consistent delimiters throughout
- UTF-8 Encoding - Use UTF-8 encoding for special characters
- Clean Data - Remove extra whitespace and formatting
- 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,500Error Handling
Common Errors
| Error | Cause | Solution |
|---|---|---|
Invalid file format | File is not CSV | Upload a valid CSV file |
Empty file | CSV has no data | Ensure file contains data rows |
Too many columns | Exceeds column limit | Reduce number of columns |
Parsing error | Malformed CSV | Check CSV formatting |
Error Response
{
"status": "error",
"errors": [
{
"row": 15,
"column": "Website",
"message": "Invalid URL format",
"value": "not-a-url"
}
]
}Best Practices
- Validate CSV - Validate CSV format before uploading
- Review Columns - Always review AI-generated column descriptions
- Clear Names - Use clear, descriptive column names
- Monitor Progress - Poll status endpoint during import
- Handle Errors - Implement error handling for failed imports
Next Steps
- Learn about Utility APIs
- View CSV Import Schemas
- Explore Workflow APIs