CSV Upload API

Upload, manage, and process CSV data files for use in document generation and email campaigns.

---

Base URL

https://app.datapublisher.io/api/csv

---

Authentication

All endpoints require JWT authentication via Authorization: Bearer header.

---

Overview

The CSV Upload API allows you to:

Upload CSV files for data storage

Analyze CSV structure (columns, data types, row counts)

Retrieve CSV data with filtering and pagination

Process CSV files row-by-row

Manage CSV file metadata and relationships

Supported File Types:

CSV files (.csv)

Text files (.txt) with comma-separated values

File Size Limit: 50 MB

---

Endpoints

Upload CSV File

Upload a CSV file for processing and storage.

Endpoint: POST /upload

Headers:

Authorization: Bearer

Content-Type: multipart/form-data

Form Data:

csvFile (file, required): CSV file to upload

description (string, optional): File description

tags (JSON array, optional): Tags for categorization

createdBy (string, optional): Creator name

Response (200 OK):

{ "success": true, "file": { "id": "uuid", "originalFilename": "customers.csv", "fileName": "abc123-def456.csv", "fileSize": 125000, "description": "Customer contact list", "tags": ["customers", "contacts"], "status": "processing" }

}

Notes:

Files are analyzed in background to extract columns and data types

Status changes from processing to completed when analysis finishes

User-specific directories are automatically created

---

List CSV Files

Get all uploaded CSV files with optional filtering.

Endpoint: GET /

Headers:

Authorization: Bearer

Query Parameters:

status (string): Filter by status (processing, completed, error)

dateFrom (ISO date): Filter from date

dateTo (ISO date): Filter to date

tags (JSON array): Filter by tags

Response (200 OK):

[ { "id": "uuid", "originalFilename": "customers.csv", "fileName": "abc123.csv", "fileSize": 125000, "description": "Customer contact list", "tags": ["customers", "contacts"], "status": "completed", "rowCount": 1500, "columnCount": 12, "relationships": [ { "relatedFileId": "uuid-2", "relatedFileName": "orders.csv", "relationshipType": "one-to-many" } ], "createdAt": "2026-02-01T10:00:00Z", "updatedAt": "2026-02-01T10:05:00Z" }

]

---

Get CSV File Metadata

Retrieve detailed metadata for a specific CSV file.

Endpoint: GET /:id

Headers:

Authorization: Bearer

Response (200 OK):

{ "id": "uuid", "userId": "user-uuid", "originalFilename": "customers.csv", "fileName": "abc123.csv", "filePath": "/uploads/user-uuid/uploads/abc123.csv", "fileSize": 125000, "description": "Customer contact list", "tags": ["customers", "contacts"], "status": "completed", "rowCount": 1500, "columnCount": 12, "columns": [ { "name": "CustomerID", "type": "number", "nullable": false }, { "name": "CompanyName", "type": "string", "nullable": false }, { "name": "ContactEmail", "type": "string", "nullable": true }, { "name": "TotalSales", "type": "number", "nullable": true } ], "createdAt": "2026-02-01T10:00:00Z", "updatedAt": "2026-02-01T10:05:00Z"

}

---

Get CSV Data

Retrieve CSV data with pagination and filtering.

Endpoint: GET /:id/data

Headers:

Authorization: Bearer

Query Parameters:

limit (number): Number of rows to return (default: 100, max: 1000)

offset (number): Number of rows to skip (default: 0)

filterColumn (string): Column name to filter

filterValue (string): Value to match in filterColumn

Response (200 OK):

{ "success": true, "headers": ["CustomerID", "CompanyName", "ContactEmail", "TotalSales"], "data": [ { "CustomerID": "1001", "CompanyName": "Acme Corp", "ContactEmail": "contact@acme.com", "TotalSales": "45000" }, { "CustomerID": "1002", "CompanyName": "TechStart Inc", "ContactEmail": "info@techstart.com", "TotalSales": "32000" } ], "metadata": { "totalRows": 1500, "returnedRows": 2, "offset": 0, "limit": 100 }

}

Performance Notes:

For large files, use pagination to avoid memory issues

Filtering is applied during streaming for efficiency

Data is returned as strings; client-side type conversion may be needed

---

Get CSV Columns

Get list of column names from a CSV file.

Endpoint: GET /:id/columns

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "columns": [

    "CustomerID",

    "CompanyName",

    "ContactEmail",

    "TotalSales",

    "Region",

    "SignupDate"

  ]

}

---

Process CSV File

Process CSV file with custom filtering and options.

Endpoint: POST /:id/process

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "filterColumn": "Region", "filterValue": "West", "limit": 500, "offset": 0

}

Response (200 OK):

{
  "success": true,

  "summary": {

    "totalRows": 1500,

    "processedRows": 450,

    "matchedRows": 450

  },

  "results": [

    {

      "CustomerID": "1005",

      "CompanyName": "West Coast Co",

      "Region": "West"

    }

  ],

  "metadata": {

    "totalRows": 1500,

    "processedRows": 450

  }

}

Use Cases:

Custom data transformations

Batch processing with business logic

Data validation and cleansing

Pre-processing before document generation

---

Delete CSV File

Permanently delete a CSV file and its data.

Endpoint: DELETE /:id

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "message": "CSV file deleted successfully"

}

Error Responses:

404 Not Found:

{
  "success": false,

  "message": "File not found or access denied"

}

---

CSV File Relationships

The API automatically detects relationships between CSV files based on:

Common column names

Data type matching

Foreign key patterns

Relationship Types:

one-to-many: One record relates to many records in another file

many-to-one: Many records relate to one record in another file

many-to-many: Complex relationships through junction tables

Example Use Case:

customers.csv (CustomerID) has one-to-many relationship with orders.csv (CustomerID)

Use relationships for data joins and complex document generation

---

Data Type Detection

The API automatically detects data types:

| Type | Detection Logic |

|------|----------------|

| number | Numeric values (integers, decimals) |

| string | Text values |

| date | ISO date formats, common date patterns |

| boolean | true/false, yes/no, 1/0 |

| email | Email address patterns |

| url | URL patterns |

---

Rate Limiting

Upload: 50 uploads per 15 minutes

Data retrieval: 1000 requests per 15 minutes

Processing: 100 requests per 15 minutes

---

Common Error Codes

| Status Code | Description |

|-------------|-------------|

| 400 | Invalid file type or format |

| 401 | Unauthorized - missing or invalid JWT token |

| 404 | File not found or access denied |

| 413 | File too large (>50 MB) |

| 429 | Too many requests - rate limit exceeded |

| 500 | Internal server error |

---

Usage Examples

JavaScript (Fetch API)

// Upload CSV
const formData = new FormData();

formData.append('csvFile', fileInput.files[0]);

formData.append('description', 'Customer contact list');

formData.append('tags', JSON.stringify(['customers', 'contacts']));


const uploadResponse = await fetch('https://app.datapublisher.io/api/csv/upload', {

  method: 'POST',

  headers: {

    'Authorization': Bearer ${jwtToken}

  },

  body: formData

});

const uploaded = await uploadResponse.json();

console.log('File uploaded:', uploaded.file.id);


// Get CSV data with pagination

const dataResponse = await fetch(

  https://app.datapublisher.io/api/csv/${fileId}/data?limit=100&offset=0,
  {

    headers: {

      'Authorization': Bearer ${jwtToken}

    }

  }

);

const csvData = await dataResponse.json();

console.log('Rows:', csvData.data.length);


// Get columns

const columnsResponse = await fetch(

  https://app.datapublisher.io/api/csv/${fileId}/columns,
  {

    headers: {

      'Authorization': Bearer ${jwtToken}

    }

  }

);

const columns = await columnsResponse.json();

console.log('Columns:', columns.columns);

Python (requests)

import requests

API_URL = 'https://app.datapublisher.io/api/csv'

headers = {'Authorization': f'Bearer {jwt_token}'}


Upload CSV

with open('customers.csv', 'rb') as f:

    files = {'csvFile': f}

    data = {

        'description': 'Customer contact list',

        'tags': '["customers", "contacts"]'

    }

    response = requests.post(f'{API_URL}/upload', files=files, data=data, headers=headers)

    uploaded = response.json()

    file_id = uploaded['file']['id']

    print(f"File uploaded: {file_id}")


Get CSV data with filtering

params = {

    'limit': 100,

    'offset': 0,

    'filterColumn': 'Region',

    'filterValue': 'West'

}

response = requests.get(f'{API_URL}/{file_id}/data', params=params, headers=headers)

csv_data = response.json()

print(f"Returned {len(csv_data['data'])} rows")


Get columns

response = requests.get(f'{API_URL}/{file_id}/columns', headers=headers)

columns = response.json()

print(f"Columns: {columns['columns']}")

cURL

Upload CSV curl -X POST https://app.datapublisher.io/api/csv/upload \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -F "csvFile=@customers.csv" \ -F "description=Customer contact list" \ -F 'tags=["customers","contacts"]' List files curl -X GET "https://app.datapublisher.io/api/csv" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" Get CSV data curl -X GET "https://app.datapublisher.io/api/csv/FILE_ID/data?limit=100&offset=0" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" Get columns curl -X GET "https://app.datapublisher.io/api/csv/FILE_ID/columns" \

-H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Best Practices

File Preparation: Clean CSV files before upload (consistent delimiters, header row, encoding)

Column Names: Use descriptive, alphanumeric column names (no special characters except underscore)

Pagination: Always use pagination for files with >1000 rows

Filtering: Apply server-side filtering instead of retrieving all data

Caching: Cache column names and metadata client-side

Error Handling: Handle processing status with polling or webhooks

File Size: Keep files under 25 MB for optimal performance

Encoding: Use UTF-8 encoding for international characters

Relationships: Name foreign key columns consistently across files

---

CSV Format Requirements

Valid CSV:

CustomerID,CompanyName,ContactEmail,TotalSales 1001,Acme Corp,contact@acme.com,45000

1002,TechStart Inc,info@techstart.com,32000

Requirements:

First row must contain header names

Comma-separated values (other delimiters not supported)

Quoted values if containing commas: "Company, Inc."

Consistent column count across all rows

UTF-8 encoding recommended

---

CSV Upload API

Base URL

Authentication

Overview

Endpoints

Upload CSV File

List CSV Files

Get CSV File Metadata

Get CSV Data

Get CSV Columns

Process CSV File

Delete CSV File

CSV File Relationships

Data Type Detection

Rate Limiting

Common Error Codes

Usage Examples

JavaScript (Fetch API)

Python (requests)

Upload CSV

Get CSV data with filtering

Get columns

cURL

Upload CSV

List files

Get CSV data

Get columns

Best Practices

CSV Format Requirements

Related Documentation