API Guide

Everything you need to integrate CSV normalization into your SaaS.

kn_test_3f91a8d2c7b84f5e9a12

curl -X POST https://csvnormalization-api-katenoji.com/v1/normalize \
  -H "X-API-Key: kn_test_3f91a8d2c7b84f5e9a12" \
  -F "file=@sample.csv"

1. Overview

The CSV Normalization API is a drop-in service that transforms messy, inconsistent CSV uploads into clean, structured JSON with predictable schemas.

Problems it solves:

• Inconsistent header naming across customer uploads
• Mixed encodings (UTF-8, Latin-1, Windows-1252)
• Unknown delimiters (commas, semicolons, tabs)
• Inconsistent null representations (N/A, null, -, empty)
• Ambiguous data types requiring manual inspection

2. When to Use This API

• Customer onboarding: When users upload contact lists, inventory data, or configuration files
• Bulk imports: Processing large datasets from external systems
• Data migrations: Converting legacy CSV exports to your internal format
• ETL pipelines: Pre-processing step before database insertion

3. When NOT to Use It

• Business-rule validation: We don't validate that emails are real or phone numbers are correct
• Data enrichment: We don't add missing data or lookup values
• UI-based editing: This is an API, not a spreadsheet editor
• Format conversion: Output is always JSON (not Excel, not another CSV)

4. Authentication

All requests to /v1/normalize require an API key passed via the X-API-Key header.

X-API-Key: kn_test_3f91a8d2c7b84f5e9a12

Contact us to obtain your API key. Keys are tied to usage tiers (free or pro) with different limits.

5. Endpoint

6. Sample CSV

Download this intentionally messy CSV to test the API:

E-Mail Address, Created At , Amount , Active
user@test.com, 01/15/2024, $1,234.56, yes
second@test.com, 15/01/2024, 999.99, no

This sample includes:

• Messy headers: Inconsistent spacing and casing
• Mixed date formats: MM/DD/YYYY vs DD/MM/YYYY
• Currency symbols: Dollar signs and thousand separators
• Boolean strings: "yes" and "no" instead of true/false

7. Expected Output

For the sample CSV above, KateNoji returns:

{
  "schema": {
    "email_address": "string",
    "created_at": "date",
    "amount": "number",
    "active": "boolean"
  },
  "data": [
    {
      "email_address": "user@test.com",
      "created_at": "2024-01-15",
      "amount": 1234.56,
      "active": true
    },
    {
      "email_address": "second@test.com",
      "created_at": "2024-01-15",
      "amount": 999.99,
      "active": false
    }
  ],
  "meta": {
    "row_count": 2,
    "original_headers": ["E-Mail Address", " Created At ", " Amount ", " Active"],
    "detected_encoding": "utf-8",
    "detected_delimiter": ",",
    "changes": [
      "Renamed 'E-Mail Address' to 'email_address'",
      "Renamed ' Created At ' to 'created_at'",
      "Renamed ' Amount ' to 'amount'",
      "Renamed ' Active' to 'active'"
    ],
    "warnings": [
      "Row 2: Ambiguous date '15/01/2024' interpreted as DD/MM/YYYY (2024-01-15)"
    ]
  }
}

8. Example Requests

curl

curl -X POST https://csvnormalization-api-katenoji.com/v1/normalize \
  -H "X-API-Key: kn_test_3f91a8d2c7b84f5e9a12" \
  -F "file=@data.csv"

JavaScript (fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('/v1/normalize', {
  method: 'POST',
  headers: {
    'X-API-Key': 'kn_test_3f91a8d2c7b84f5e9a12'
  },
  body: formData
});

const result = await response.json();

Python (requests)

import requests

with open('data.csv', 'rb') as f:
    response = requests.post(
        'https://csvnormalization-api-katenoji.com/v1/normalize',
        headers={'X-API-Key': 'kn_test_3f91a8d2c7b84f5e9a12'},
        files={'file': f}
    )

result = response.json()

9. Limits

10. Common Errors

All errors return a consistent JSON structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

401 Unauthorized

Meaning: Missing or invalid API key.

How to fix: Include a valid X-API-Key header. Check for typos in your key.

413 Payload Too Large

Meaning: File exceeds the size limit for your tier.

How to fix: Free tier allows 1MB max. Split your file or upgrade to Pro (10MB).

400 Bad Request

Meaning: Empty file, invalid CSV format, or missing file field.

How to fix: Ensure the file is a valid CSV with at least one header row. Use file as the form field name.

429 Rate Limit Exceeded

Meaning: Daily or monthly request limit reached.

How to fix: Wait until the next day (daily reset) or next month (monthly reset). Consider upgrading for higher limits.

11. Privacy

• In-memory processing: CSV files are processed entirely in memory
• No storage: We do not store your CSV content on disk or in databases
• No logging of data: Only metadata (row counts, errors) is logged—never your actual data
• Stateless: Each request is independent; we retain nothing between calls