Reference

Import payload

Reference for CSVJetty callback and webhook import payload fields, row numbers, matched columns, unmatched data, and callback error responses.

View as Markdown

On this page

Payload shape Payload fields Row numbers Unmatched data Callback result

Callback and webhook delivery share the same core import payload. The payload preserves enough source context to save records safely and report row-level errors against the original CSV.

Payload shape

{  importId: "IMPORT_ID",  fileName: "contacts.csv",  rows: [    {      name: "Ada",      email: "ada@example.com",    },  ],  rowNumbers: [1],  skippedRows: 0,  uploadedFileHeaders: ["Full Name", "Email"],  matchedColumnsMap: {    name: "Full Name",    email: "Email",  },}

Payload fields

Field	Type	Purpose
`importId`	string	Unique ID for the import. Use it as part of your idempotency strategy.
`fileName`	string	Sanitized name of the uploaded CSV file.
`rows`	array	Mapped and cleaned records for this delivery batch.
`rowNumbers`	number[]	Original data-row numbers corresponding to rows in this batch.
`skippedRows`	number	Number of invalid rows excluded when invalid-row filtering is enabled.
`uploadedFileHeaders`	string[]	Headers found in the uploaded CSV.
`matchedColumnsMap`	object	Destination field name to selected source-header mapping.
`batch`	number	Webhook only: zero-based batch number.
`totalBatches`	number	Webhook only: total number of batches.

Row numbers

Row numbers start at 1 for the first data row after the CSV header. They keep their original source-row identity when invalid rows are filtered out, so you can return errors for the correct original record.

Pair importId with row or batch identity when your receiving API needs idempotent writes.

Unmatched data

When Include unmatched columns is enabled, each delivered row can contain an _unmatched object with source fields that were not mapped to configured destination columns.

{  email: "ada@example.com",  _unmatched: {    "Legacy ID": "1234"  }}

Learn when to use this in Column mapping.

Callback result

Return nothing or an empty errors array when a callback batch succeeds.

return { errors: [] };

Reject individual original CSV rows with:

return {  errors: [    { row: 2, message: "Email already exists" },  ],};

Error messages must be nonempty and are associated with the original row number supplied in rowNumbers.

Component props

Limits & requirements