# CSV Import Preflight — Validate, Map & Audit (`frantz-ai-automation/csv-import-preflight`) Actor

Validate CSV files against an explicit import contract. Get a prepared CSV, column mapping, raw-value-free issue report, reconciliation audit, and integrity manifest—without AI guesswork or silent data invention.

- **URL**: https://apify.com/frantz-ai-automation/csv-import-preflight.md
- **Developed by:** [François Tissier](https://apify.com/frantz-ai-automation) (community)
- **Categories:** Automation, Business, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.75 / csv preflight up to 1,000 rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## CSV Import Preflight — Validate, Map & Audit

Validate a CSV against an explicit import contract before it reaches your CRM,
ERP, accounting tool, marketplace, or internal database. The Actor returns a
prepared CSV only when every row passes, plus a mapping, raw-value-free issue
report, machine-readable audit report, and integrity manifests.

**No AI guesswork. No silent data invention. No in-place modification of the
source file.**

### What this Actor is for

- verify headers and column order before an import;
- map source columns to target columns;
- normalize explicitly declared integers, decimals, dates, emails, and text;
- reject undeclared, missing, malformed, or ambiguous values;
- protect spreadsheet formula-like text;
- prove which source and schema were processed with SHA-256 hashes;
- automate repeatable CSV quality gates through Apify Console or API.

This Actor is a deterministic import preflight, not a generic “repair anything”
cleaner. It never guesses an encoding, delimiter, type, date convention, or
decimal convention.

### Quick start

1. Upload one source CSV in **Source CSV**. External URLs are intentionally not
   accepted; upload the file to Apify storage through the file picker.
2. Choose one contract mode:
   - **Header-only CSV template** for text-only validation and target ordering;
   - **Typed JSON schema** for explicit mapping and typed validation.
3. Run the Actor.
4. Open **Output** for the summary and **Audit files** for the downloadable
   deliverables.

Use the example files as matched pairs:

- `source-header-only-valid.csv` with `target-header-only.csv`;
- `source-valid.csv` with `typed_schema.json`.

Do not combine the source from one pair with the contract from the other.

### Contract modes

#### Header-only CSV template

Upload a second CSV containing exactly one header row and no data. All target
columns remain text because the Actor does not infer types. Choose the source
and output encodings, delimiters, header-order policy, and formula policy in the
input form. The bundled `source-header-only-valid.csv` and
`target-header-only.csv` are a compatible example pair.

#### Typed JSON schema

Supply an explicit `frantz.csv-import.schema.v2` object. The bundled
`source-valid.csv` and `typed_schema.json` are a compatible example pair. The
schema explicitly maps `source_id`, `amount`, `date`, and `contact_email` to
their target columns; it is not intended for the header-only example.

Supported column types:

- `text`
- `integer`
- `decimal`
- `date` (`iso`, `dmy_slash`, or `dmy_dash`)
- `email`

Supported explicit rules include required/optional values, trimming, maximum
length, allowed values, negative-number policy, decimal separator, source-to-
target mapping, constants, exact value maps, ignored source columns, strict or
flexible header order, and formula escape/reject policy.

### Outputs

The default dataset contains one summary item without source cell values:

```json
{
  "status": "accepted",
  "rows": 2,
  "inputColumns": 4,
  "outputColumns": 4,
  "issueCount": 0,
  "protectedFormulaCells": 0,
  "normalizedCells": 5,
  "sourceSha256": "7f23a6e0fbbc1e8cd293d60a018a62441746e6daec2afa509c8d851d1aab5a95",
  "schemaSha256": "cc4fb4805c37c4e4725df2b5a64be5c2a0cb43e7a1042053cc7d37e8ec31c492",
  "billingEvent": "csv-preflight-small",
  "billingOperationId": "frantz-csv-preflight-v1-078c1eb66e14513882c53569f5e7f7d4",
  "manifestSha256": "4c6b6629dceb513a374ff4694a852ded3c940f00f17da8ec8eef4b1c961f5a1b",
  "preparedCsvEmitted": true,
  "manifestKey": "deliverable-MANIFEST.json"
}
```

The default key-value store contains:

| Key | Purpose |
| --- | --- |
| `deliverable-prepared.csv` | Prepared CSV; emitted only when status is `accepted` |
| `deliverable-mapping.csv` | Declared source-to-target mapping and presence flags |
| `deliverable-issues.csv` | Issue coordinates, codes, and rejected-value character lengths; no raw values or per-value hashes |
| `deliverable-report.json` | Full validation and reconciliation report |
| `deliverable-engine-manifest.json` | Manifest produced by the deterministic validation engine |
| `deliverable-MANIFEST.json` | Actor-level manifest sealing every business artifact |
| `deliverable-summary.json` | Canonical copy of the dataset summary, anchoring the Actor manifest hash |

`rejected` is a valid business outcome: the audit files explain why the CSV is
not safe to import, and no prepared CSV is emitted.

### Transparent pricing

This Actor uses pay per event with platform usage included:

| Event | Price |
| --- | ---: |
| CSV preflight up to 1,000 data rows | $0.75 |
| CSV preflight from 1,001 to 2,000 data rows | $1.50 |
| Apify Actor start (automatic synthetic event) | $0.00005 |

The selected size event is charged once only after verified deliverables are
published. Invalid Actor configuration, unreadable uploads, hard-limit errors,
or internal failures do not trigger a CSV preflight event. A business rejection
after a completed audit is charged because the issue report is the delivered
result.

The runtime fails closed if Apify is not configured for PPE, if either custom
event is not one-time, if any published event price differs from the table
above, or if `apify-default-dataset-item` exists at all (flat or tier-priced).

### Version 1 limits

| Limit | Value |
| --- | ---: |
| Source files | 1 |
| Source size | 10 MiB |
| Data rows | 2,000 |
| Source columns | 40 |
| Target columns | 30 |
| Encodings | UTF-8 with/without BOM, Windows-1252 |
| Delimiters | comma, semicolon, tab, pipe |

Quoted fields and embedded delimiters are supported by the standard CSV parser.
XLSX, generic download URLs, fuzzy matching, deduplication, and type inference
are deliberately outside version 1.

### Privacy and security

- no third-party API, proxy, browser, LLM, or remote enrichment call;
- uploaded URLs are restricted to signed or accessible Apify key-value-store
  record URLs, preventing generic URL fetching and SSRF;
- bounded streaming stops oversized uploads, and a logical-row guard rejects
  excess CSV records before the validation engine can materialize them;
- the container runs as a non-root user;
- source cell values are never written to logs or the summary dataset;
- issue records contain only the rejected value's character length; the
  engine's per-value hash field is blanked before export;
- the source file is not copied into output storage;
- dependency and engine versions are pinned; Linux build wheels are restricted
  to exact SHA-256 hashes;
- the source upload and generated outputs follow the retention and access rules
  of the user's Apify storages and plan.

The accepted prepared CSV necessarily contains the validated output values. Do
not share a run or its storage links with unauthorized people.

### Status semantics

- `accepted`: every row passed; `deliverable-prepared.csv` is available.
- `rejected`: the audit completed but one or more business rules failed; inspect
  `deliverable-issues.csv` and `deliverable-report.json`.
- failed run: the contract, upload, billing configuration, resource limit, or
  platform operation could not be proven safe; no success is reported.

### Reliability notes

Every delivery is generated locally inside the Actor, verified against the
engine manifest, namespaced in the default key-value store, and sealed again by
an Actor-level manifest. Its SHA-256 is anchored in the canonical summary stored
both in the key-value store and the run dataset. The summary is written before
the custom charge. Charging uses a deterministic idempotency key through the
run charge endpoint, while recovery cross-checks custom-event counts, the single
dataset item, the summary, the manifest, and every artifact hash. Ambiguous
platform state fails closed and retains the verified evidence for safe recovery.

### Support

Use the Actor's **Issues** tab on Apify for reproducible defects and usage
questions. Include the run ID and the observed status, but never post a source
CSV, signed storage URL, API token, or customer data in a public issue. Support
responses target one business day.

### Version

Actor version `0.1`; deterministic engine version `2.0.0`.

# Actor input Schema

## `sourceFile` (type: `string`):

Upload exactly one CSV file, up to 10 MiB and 2,000 data rows. Generic external URLs are rejected. The uploaded file remains in Apify storage according to your plan's retention settings.

## `contractMode` (type: `string`):

Use a header-only target CSV for text-only checks, or an explicit JSON schema for typed validation and mapping.

## `targetModelFile` (type: `string`):

Required in header-template mode. Upload a CSV containing exactly one header row and no data. Generic external URLs are rejected. No type is inferred.

## `typedSchema` (type: `object`):

Required in typed-schema mode. Explicit versioned rules for columns, mappings, types, formats and limits. Unknown fields are rejected.

## `inputEncoding` (type: `string`):

Used only in header-template mode.

## `inputDelimiter` (type: `string`):

Used only in header-template mode.

## `outputEncoding` (type: `string`):

Used only in header-template mode.

## `outputDelimiter` (type: `string`):

Used only in header-template mode.

## `headerOrder` (type: `string`):

Strict requires the same order. Flexible accepts a different order and emits the target order.

## `formulaPolicy` (type: `string`):

Escape protects formula-like text in the prepared CSV. Reject fails the affected rows instead.

## Actor input object example

```json
{
  "contractMode": "header-template",
  "inputEncoding": "utf-8-sig",
  "inputDelimiter": "semicolon",
  "outputEncoding": "utf-8-sig",
  "outputDelimiter": "semicolon",
  "headerOrder": "flexible",
  "formulaPolicy": "escape"
}
```

# Actor output Schema

## `summary` (type: `string`):

Machine-readable summary with status, counts, hashes and artifact names. No cell values are included.

## `auditFiles` (type: `string`):

Prepared CSV when accepted, issue report, mapping, JSON report and integrity manifest.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("frantz-ai-automation/csv-import-preflight").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("frantz-ai-automation/csv-import-preflight").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call frantz-ai-automation/csv-import-preflight --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,frantz-ai-automation/csv-import-preflight"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MUyXjQ17ElAkBEw5M/builds/GGNCADggJoreibKFe/openapi.json