Trillet AI logo

Validate Batch CSV

Check a batch-call CSV before starting the batch.

POSThttps://api.trillet.ai/v1/api/batch-calls/validate

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

This endpoint accepts multipart/form-data.

filefilerequired

CSV file to validate. Maximum file size: 20MB. Use the columns from Download Batch CSV Template.

A CSV with invalid rows still returns HTTP 200. Check the valid field, not the status code. Rows with errors are skipped when you start the batch.

Response

validboolean

true when no row has an error or warning.

totalRecordsnumber

Number of data rows in the file.

validRecordsnumber

Number of rows without errors. These are the rows a batch would call.

previewarray

The first 5 rows after normalization (phone numbers formatted to E.164). Each row has an internal _hasErrors flag.

allRecordsarray

Every row after normalization, including rows with errors.

validationErrorsarray | null

One entry per row with problems, or null when there are none.

hasWarningsOnlyboolean

true when there are issues but all of them are warnings (for example a value over 500 characters). Rows with only warnings are still called.

messagestring

"Successfully validated N records" or "Found issues in X out of N records".

Example

curl -X POST "https://api.trillet.ai/v1/api/batch-calls/validate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@contacts.csv"

Example Response

{
  "valid": false,
  "totalRecords": 2,
  "validRecords": 1,
  "preview": [
    { "phone_number": "+14155550123", "contact_name": "John Smith", "_hasErrors": false },
    { "phone_number": "12ab", "contact_name": "Jane Doe", "_hasErrors": true }
  ],
  "allRecords": [
    { "phone_number": "+14155550123", "contact_name": "John Smith", "_hasErrors": false },
    { "phone_number": "12ab", "contact_name": "Jane Doe", "_hasErrors": true }
  ],
  "validationErrors": [
    {
      "rowNumber": 3,
      "errors": [
        {
          "field": "phone_number",
          "message": "Phone number contains invalid characters",
          "rowNumber": 3,
          "value": "12ab",
          "severity": "error"
        },
        {
          "field": "phone_number",
          "message": "Phone number must be in international format with + prefix",
          "rowNumber": 3,
          "value": "12ab",
          "severity": "error",
          "suggestion": "Format as +[country code][number], e.g., +12125551234"
        }
      ]
    }
  ],
  "hasWarningsOnly": false,
  "message": "Found issues in 1 out of 2 records"
}

Error Responses

400 with {"valid": false, "error": "..."} when no file is uploaded, the file can't be parsed as CSV, or it has no data rows.

Last updated on