> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate Import

> Validate mapped rows and return paginated row-level results

# 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.

<Note>
  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).
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Path Parameters

<ParamField path="import_id" type="string" required>
  UUID of the import session

  **Example:** `"11111111-1111-1111-1111-111111111111"`
</ParamField>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (1-indexed)
</ParamField>

<ParamField query="page_size" type="integer" default="50">
  Rows per page (1–500)
</ParamField>

<ParamField query="errors_only" type="boolean" default="false">
  When `true`, only return rows with validation errors
</ParamField>

### Body Parameters

<ParamField body="mapping" type="object" required>
  Column mapping to use for validation: `{target_column: source_column | null}`

  **Example:** `{"origin": "origin", "destination": "destination", "weight": "weight_kg"}`
</ParamField>

<ParamField body="value_mappings" type="object">
  User-defined value remappings for category columns. Map of `{target_column: {raw_value: canonical_value}}`.

  **Example:** `{"vehicle_type": {"Camión": "truck", "Furgoneta": "van"}}`
</ParamField>

## Response

<ResponseField name="import_id" type="string">
  UUID of the import session
</ResponseField>

<ResponseField name="total_rows" type="integer">
  Total number of data rows
</ResponseField>

<ResponseField name="valid_rows" type="integer">
  Number of rows that passed validation
</ResponseField>

<ResponseField name="error_rows" type="integer">
  Number of rows with at least one validation error
</ResponseField>

<ResponseField name="errors_by_column" type="object">
  Error counts per column key. Example: `{"weight": 2, "date": 1}`
</ResponseField>

<ResponseField name="shape_warnings" type="object">
  Warnings about the overall data shape (e.g. missing columns)
</ResponseField>

<ResponseField name="rows" type="array[object]">
  Paginated row-level validation output

  <Expandable title="Row Object">
    <ResponseField name="row_index" type="integer">
      Zero-based index of the row in the original file
    </ResponseField>

    <ResponseField name="data" type="object">
      Row data keyed by target column name
    </ResponseField>

    <ResponseField name="errors" type="object">
      Validation errors keyed by column. Each value is an array of error objects with `rule`, `params`, and `message`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="page_size" type="integer">
  Rows per page
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Total number of pages
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"}
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  headers = {
      "x-api-key": os.getenv("DCYCLE_API_KEY"),
      "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      "Content-Type": "application/json",
  }

  import_id = "11111111-1111-1111-1111-111111111111"

  response = requests.post(
      f"https://api.dcycle.io/v2/imports/{import_id}/validate",
      headers=headers,
      params={"page": 1, "page_size": 50, "errors_only": False},
      json={
          "mapping": {
              "origin": "origin",
              "destination": "destination",
              "weight": "weight_kg",
              "vehicle_type": "vehicle_type",
              "date": "date",
          },
          "value_mappings": {
              "vehicle_type": {"Camión": "truck", "Furgoneta": "van"}
          },
      },
  )

  result = response.json()
  print(f"Valid: {result['valid_rows']}/{result['total_rows']}")
  print(f"Errors: {result['error_rows']} rows")
  for row in result["rows"]:
      if row["errors"]:
          print(f"  Row {row['row_index']}: {row['errors']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
    'Content-Type': 'application/json',
  };

  const importId = '11111111-1111-1111-1111-111111111111';

  axios.post(`https://api.dcycle.io/v2/imports/${importId}/validate`, {
    mapping: {
      origin: 'origin',
      destination: 'destination',
      weight: 'weight_kg',
      vehicle_type: 'vehicle_type',
      date: 'date',
    },
    value_mappings: {
      vehicle_type: { 'Camión': 'truck', 'Furgoneta': 'van' },
    },
  }, {
    headers,
    params: { page: 1, page_size: 50, errors_only: false },
  }).then(response => {
    const { valid_rows, total_rows, error_rows } = response.data;
    console.log(`Valid: ${valid_rows}/${total_rows}, Errors: ${error_rows}`);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Not found."
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Confirm Mapping" icon="check" href="/api-reference/imports/confirm-mapping">
    Persist the mapping before validating
  </Card>

  <Card title="Submit Import" icon="paper-plane" href="/api-reference/imports/submit">
    Submit the validated session for processing
  </Card>

  <Card title="Get Unique Values" icon="list-check" href="/api-reference/imports/get-unique-values">
    Inspect category values before validation
  </Card>

  <Card title="Import Overview" icon="upload" href="/api-reference/imports/overview">
    Full workflow guide
  </Card>
</CardGroup>