Skip to main content
POST
/
v2
/
imports
/
{import_id}
/
validate
Validate Import
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({mapping: {}, value_mappings: {}})
};

fetch('https://api.dcycle.io/v2/imports/{import_id}/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "import_id": "<string>",
  "total_rows": 123,
  "valid_rows": 123,
  "error_rows": 123,
  "errors_by_column": {},
  "shape_warnings": {},
  "rows": {
    "row_index": 123,
    "data": {},
    "errors": {}
  },
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

​
Validate Import

Run validation on the import session using the specified column mapping. Returns a summary of valid/error rows plus paginated row-level validation results. Use errors_only=true to focus on rows that need attention.
You can optionally include value_mappings to pre-resolve category values the user remapped by hand (e.g. mapping "Camión" → "truck" for the vehicle_type column).

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Path Parameters

​
import_id
string
required
UUID of the import sessionExample: "11111111-1111-1111-1111-111111111111"

​
Query Parameters

​
page
integer
default:"1"
Page number (1-indexed)
​
page_size
integer
default:"50"
Rows per page (1–500)
​
errors_only
boolean
default:"false"
When true, only return rows with validation errors

​
Body Parameters

​
mapping
object
required
Column mapping to use for validation: {target_column: source_column | null}Example: {"origin": "origin", "destination": "destination", "weight": "weight_kg"}
​
value_mappings
object
User-defined value remappings for category columns. Map of {target_column: {raw_value: canonical_value}}.Example: {"vehicle_type": {"Camión": "truck", "Furgoneta": "van"}}

​
Response

​
import_id
string
UUID of the import session
​
total_rows
integer
Total number of data rows
​
valid_rows
integer
Number of rows that passed validation
​
error_rows
integer
Number of rows with at least one validation error
​
errors_by_column
object
Error counts per column key. Example: {"weight": 2, "date": 1}
​
shape_warnings
object
Warnings about the overall data shape (e.g. missing columns)
​
rows
array[object]
Paginated row-level validation output
​
page
integer
Current page number
​
page_size
integer
Rows per page
​
total_pages
integer
Total number of pages

​
Example

curl -X POST "https://api.dcycle.io/v2/imports/11111111-1111-1111-1111-111111111111/validate?page=1&page_size=50&errors_only=false" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": {
      "origin": "origin",
      "destination": "destination",
      "weight": "weight_kg",
      "vehicle_type": "vehicle_type",
      "date": "date"
    },
    "value_mappings": {
      "vehicle_type": {"Camión": "truck", "Furgoneta": "van"}
    }
  }'

​
Successful Response

{
  "import_id": "11111111-1111-1111-1111-111111111111",
  "total_rows": 240,
  "valid_rows": 237,
  "error_rows": 3,
  "errors_by_column": {
    "weight": 2,
    "date": 1
  },
  "shape_warnings": {},
  "rows": [
    {
      "row_index": 0,
      "data": {
        "origin": "Madrid",
        "destination": "Barcelona",
        "weight": "1500",
        "vehicle_type": "truck",
        "date": "2024-03-15"
      },
      "errors": {}
    },
    {
      "row_index": 14,
      "data": {
        "origin": "Valencia",
        "destination": "Sevilla",
        "weight": "abc",
        "vehicle_type": "van",
        "date": "2024-03-16"
      },
      "errors": {
        "weight": [
          {
            "rule": "type_numeric",
            "params": {"value": "abc"},
            "message": "Expected a numeric value"
          }
        ]
      }
    }
  ],
  "page": 1,
  "page_size": 50,
  "total_pages": 5
}

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

​
403 Forbidden

Cause: The authenticated user is not a member of the organization 
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

​
404 Not Found

Cause: Import session does not exist or does not belong to your organization 
{
  "detail": "Not found."
}

Confirm Mapping

Persist the mapping before validating

Submit Import

Submit the validated session for processing

Get Unique Values

Inspect category values before validation

Import Overview

Full workflow guide