Configure a File Connector

The File connector lets you run an import job on a CSV file you upload yourself, without configuring an external source such as an SFTP server or a pull API.

It is designed for one-off imports: you reuse the mapping and the rules already defined on a job, and you simply provide the file to process. Existing jobs and their current connectors are not impacted.

Key concepts

📘

Note: The File connector is available on import jobs only. Export jobs continue to rely on the FTP and API connectors.

Typical workflow

The file is uploaded first, then referenced on the job, then the job is triggered — immediately or later.

flowchart LR
  A[📦 Upload CSV<br>with delimiter]:::create --> B[🧾 Check metadata<br>columns • rowCount • preview]:::read
  B --> C{File correct}:::decision
  C -->|No| D[➖ Delete file<br>and upload again]:::remove
  C -->|Yes| E[➕ Attach fileId<br>to the import job]:::add
  D --> A
  E --> F[✅ Start the job]:::place
  F --> G[📘 Execution history<br>carries the file name]:::read

  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef add      fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef remove   fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  style A rx:8,ry:8
  style B rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style E rx:8,ry:8
  style F rx:8,ry:8
  style G rx:8,ry:8

Step by step

1. Upload the CSV file. Send the file with the delimiter used to parse it. The response returns the file identifier and the derived metadata, so you can check the columns and the first rows before going further.
2. Check the parsed result. Confirm that the column list matches your mapping and that the row count is the expected one. If the delimiter was wrong, delete the file and upload it again.
3. Attach the file to a job. Create an import job with a FILE step configuration carrying the fileId, or update an existing job to point at the newly uploaded file.
4. Trigger the job. Start it right away, or leave it attached and start it later — as long as the file has not been purged.
5. Follow the execution. The execution history of the job carries the name of the processed file, so you can tell which file each execution handled.

Key endpoints involved

All of these are administration endpoints: dj-client: OPERATOR and a valid dj-api-key are required.

Example scenarios

1. Upload a CSV file

The delimiter is required — it is the character used to parse the file, and there is no default value.

POST /v1/import/files?delimiter=%3B
dj-client: OPERATOR
dj-api-key: <your-api-key>
Content-Type: multipart/form-data

[email protected]

Response 201 Created:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "offers-2026-08.csv",
  "sizeBytes": 48213,
  "rowCount": 512,
  "columns": ["offer_external_id", "supplier_external_id", "price", "stock"],
  "preview": [
    {
      "offer_external_id": "OFF-0001",
      "supplier_external_id": "SUP-01",
      "price": "12.50",
      "stock": "120"
    },
    {
      "offer_external_id": "OFF-0002",
      "supplier_external_id": "SUP-01",
      "price": "18.90",
      "stock": "45"
    }
  ],
  "uploadedAt": "2026-08-20T09:14:22.000Z",
  "expiresAt": "2026-08-27T09:14:22.000Z"
}

⚠️

Warning: A 400 is returned when the file format or the delimiter is not supported, or when the file exceeds the accepted size. If columns comes back as a single concatenated column, the delimiter you sent does not match the file.

2. Attach the file to an import job

Two things identify a File connector job: the client configuration type FILE_CLIENT on jobTypeInfo, and a stepConfiguration of type FILE carrying the fileId returned at upload. No connector credentials are needed, so clientConfigurationId can be omitted.

{
  "jobName": "Offers - manual import August",
  "jobTypeInfo": {
    "clientConfigurationType": "FILE_CLIENT",
    "genericJobType": "OFFER",
    "readerConfigurationType": "CSV"
  },
  "readerConfiguration": {
    "type": "CSV",
    "delimiter": ";",
    "mappings": []
  },
  "stepConfiguration": {
    "type": "FILE",
    "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

📘

Note: mappings is shown empty here for readability. It must contain the column mapping of your entity — see Data Hub Mapping Overview.

On an existing job, send the same stepConfiguration through PATCH /v2/mapper/jobs/{jobId} to point it at a new file without touching the mapping.

3. Trigger the job

GET /v1/mapper/jobs/start/2f8a1c94-7b3e-4d21-9a55-6c0d1e3f7b02
dj-client: OPERATOR
dj-api-key: <your-api-key>

Response: 204 No Content. The job runs on the attached file, using the mapping and rules already configured.

4. Inspect or remove an uploaded file

GET /v1/import/files/f47ac10b-58cc-4372-a567-0e02b2c3d479

Returns the same metadata as the upload response, including expiresAt. A 404 means the file never existed or has already been purged.

DELETE /v1/import/files/f47ac10b-58cc-4372-a567-0e02b2c3d479

Returns 204 No Content. If the file was attached to a job, it is detached from it first — the job itself is preserved.

Best practices

• Always check the metadata before triggering. The columns and rowCount returned at upload are the cheapest way to catch a wrong delimiter or a truncated export, before any data reaches the platform.
• Reuse an existing job rather than creating one per file. The point of the File connector is to reuse a mapping that is already validated. Point the same job at a new fileId for each run.
• Trigger inside the retention window. Read expiresAt and start the job before that date. For a deferred run, plan the upload accordingly rather than uploading far in advance.
• Keep the delimiter consistent between the upload call and the reader configuration of the job.
• Use the execution history to audit. Each execution carries the name of the file it processed, which remains available even after the file has been purged.
• Prefer FTP or API connectors for recurring flows. The File connector is for occasional imports; an automated flow should still rely on a scheduled source.

Common mistakes

Error codes

Validation and business errors follow the platform conventions. See the dedicated page: Error / Warning codes.