Server-Side Validation

​

How it works

1

Activate server-side validation in the sheet settings

Go to Edit Sheet → Destination tab → enable Server Side Validation.

The External Validation option is available only for the API data destination.

2

Users upload and submit the spreadsheet

Users upload the spreadsheet, map columns, verify data, and then submit.

3

The importer pushes the data to your API endpoint

The importer sends the spreadsheet data via POST requests with JSON values to the API endpoint you configured. The request schema is available here.

4

Your app processes and validates the data

Your app validates the data against your business rules:

• Validation succeeds (no errors found): your API returns a 200 HTTP response code, and the user sees the success screen.
• Validation fails (one or more errors found): your API returns a 211 HTTP response code along with the validation errors in JSON format. See the error response format.

Your API must return the 211 HTTP response status code to tell the CSVbox importer that there are one or more server-side validation errors.To view the results screen, configure the CSVbox Results Page settings: go to Sheet Settings → Display → Results Page and set Closing the import dialog box to Do not close on import complete.

5

Users see the validation fail screen

If there are one or more server-side validation errors, users see the fail screen with a button to view the errors.

6

Users view the validation errors

Clicking the Errors button takes users to the Verify Data screen with all the server-side errors displayed.

7

Users fix the errors and re-submit the data

On re-submit, the process repeats: the importer pushes the data to your API endpoint via POST requests and looks for errors in the response.

Each re-submit is treated as a fresh import with a new Import_Id.

To let users re-submit all the rows (instead of only the error rows), select the All Rows option as shown below:

​

Error types

• table: Shows high-level or common errors that apply to the entire upload. Renders as a dismissible alert above the grid.
• row: Shows errors that apply to a whole row, not a specific cell. Renders as a red badge on the row number; clicking it opens a pop-up with the message.
• column: Shows validation errors that apply to an entire column. Use these when the issue is with the column itself rather than with any individual row or cell.
• cell: The previous behavior; highlights an individual cell with an inline message. This documentation refers to these as “cell errors.”

​

UI behavior

• Table errors appear in a prominent alert banner above the grid until dismissed or replaced by a subsequent validation run.
• Row errors highlight the row index with a red badge. Clicking the badge opens a pop-over containing your message.
• Column errors highlight the column name with a red badge. Clicking the badge opens a pop-over containing your message.
• Cell errors continue to highlight individual cells with inline messages as before.

​

When to use each type

• table: Missing required columns, inconsistent file format, duplicate file, or any condition that makes the whole dataset invalid.
• row: Cross-field checks within the same row (for example, “End Date must be after Start Date”), referential issues that aren’t tied to a single column, or row-level business rules.
• column: Issues that apply to a full column rather than to one cell or row (for example, an invalid column name, or a required column with an incorrect format or configuration).
• cell: Format, length, or pattern errors, disallowed values, or any validation that is clearly attributable to one column.

​

Response format JSON

​

Fields

​

Example payload

[
  {
    "type": "table",
    "message": "Missing address.<br>Missing department.<br>Resubmit."
  },
  {
    "type": "cell",
    "row_id": 1,
    "column": "employee_id",
    "message": "Invalid Emp ID"
  },
  {
    "row_id": 2,
    "column": "dept",
    "message": "Department does not exist"
  },
  {
    "row_id": 3,
    "column": "employee_name",
    "message": "Employee's name has changed"
  },
  {
    "type": "row",
    "row_id": 3,
    "message": "Cannot add this row"
  },
  {
     "type": "column",
     "column": "employee_id",
     "message": "Invalid column name"
  }
]

​

Additional attributes in the client data object

​

Example response object

{
  destination_type: "apiwebhook",
  env_name: "default",
  import_description: "",
  import_endtime: 1762774689,
  import_id: 12859532,
  import_starttime: 1762774686,
  import_status: "success",
  original_filename: "emp.csv",
  raw_file: "https://app.csvbox.io/download-rawfile/1-FIIeyMflK9OvAX1EMjncCTlMasuG5Vil35LQNHAQ",
  row_count: 5,
  row_fail: 0,
  row_success: 5,
  sheet_id: 1058,
  sheet_name: "Customer onboarding",
  ssv_enabled: 1,
  ssv_fail: 1,
  ssv_row_fail: 3,
  ssv_table_error: 1
}

• ssv_enabled confirms that SSV is active.
• ssv_fail is true because the server responded with a 211 code.
• ssv_row_fail specifies the number of failed rows.
• ssv_table_error is false, meaning the issue was at the row level rather than a table-level error.