--- title: "Preview import" description: "Validates and previews the uploaded rows without changing catalog data. Returns mappings, row counts, missing fields, and representative skipped rows." language: en canonical_url: "https://exac.mx/docs/en/api/catalog/imports/preview-import" md_url: "https://exac.mx/docs/en/api/catalog/imports/preview-import.md" --- # Preview import Validates and previews the uploaded rows without changing catalog data. Returns mappings, row counts, missing fields, and representative skipped rows. ## Request `POST /v1/imports/uploads/{uploadRef}/preview` - **Authorization:** Required permission: `imports:read`. - **Environments:** Production only - **Idempotency:** Not required ## Canonical machine contract This fragment is generated from the canonical operation and Zod contracts used by the route. ```json { "method": "POST", "path": "/v1/imports/uploads/{uploadRef}/preview", "operation": { "operationId": "previewImport", "tags": [ "Imports" ], "summary": "Preview import", "description": "Validates and previews the uploaded rows without changing catalog data. Returns mappings, row counts, missing fields, and representative skipped rows.", "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://adventurous-moose-616.convex.site", "description": "Current Exac production API deployment" } ], "parameters": [ { "name": "uploadRef", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^upload:", "description": "Opaque uploadRef returned when an import upload is prepared" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Operation completed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fileRows": { "type": "number" }, "sourceFormat": { "type": "string", "enum": [ "xml", "csv", "excel", "html", "database", "unknown" ] }, "sourceSoftware": { "type": "string" }, "totalRows": { "type": "number" }, "validRows": { "type": "number" }, "skippedRows": { "type": "number" }, "newRows": { "type": "number" }, "updateRows": { "type": "number" }, "sourceColumns": { "type": "array", "items": { "type": "string" } }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "fieldKey": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "number", "money", "boolean" ] }, "required": { "type": "boolean" }, "important": { "type": "boolean" }, "sourceColumn": { "type": "string" }, "status": { "type": "string", "enum": [ "mapped", "missing" ] } }, "required": [ "fieldKey", "label", "kind", "required", "important", "status" ], "additionalProperties": false } }, "unmappedSourceColumns": { "type": "array", "items": { "type": "string" } }, "missingRequiredFields": { "type": "array", "items": { "type": "string" } }, "missingImportantFields": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "skippedSamples": { "type": "array", "items": {} }, "duplicateSamples": { "type": "array", "items": {} }, "duplicateCodeRows": { "type": "number" }, "duplicateDescriptionRows": { "type": "number" }, "duplicateSourceKeyRows": { "type": "number" }, "duplicateCodeSamples": { "type": "array", "items": {} }, "duplicateSourceKeySamples": { "type": "array", "items": {} }, "hasPrices": { "type": "boolean" }, "hasStock": { "type": "boolean" }, "fiscalReadyRows": { "type": "number" } }, "required": [ "fileRows", "sourceFormat", "totalRows", "validRows", "skippedRows", "newRows", "updateRows", "sourceColumns", "fieldMappings", "unmappedSourceColumns", "missingRequiredFields", "missingImportantFields", "sampleRows", "skippedSamples" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "fileRows": 10, "sourceFormat": "xml", "totalRows": 10, "validRows": 10, "skippedRows": 0, "newRows": 8, "updateRows": 2, "sourceColumns": [ "description", "price" ], "fieldMappings": [], "unmappedSourceColumns": [], "missingRequiredFields": [], "missingImportantFields": [], "sampleRows": [], "skippedSamples": [] } } } } }, "400": { "description": "Invalid request.\n\n`validation_error`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid credential.\n\n`unauthenticated`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The credential does not include the `imports:read` permission.\n\n`forbidden`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found.\n\n`not_found`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Method not allowed.\n\n`method_not_allowed`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests.\n\n`rate_limited`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error.\n\n`internal`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service temporarily unavailable.\n\n`provider_unavailable`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-exac-environments": [ "production" ] }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProgrammaticError" } }, "required": [ "error" ], "additionalProperties": false }, "ProgrammaticError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "rate_limited", "provider_unavailable", "internal" ], "description": "Recommended action by code:\n\n- `validation_error` — Correct each details.issues entry using its path and stable issue code.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically; reconcile the provider outcome.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — Retry later and contact support if the error persists." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message", "status" ], "additionalProperties": false } } } } ``` [OpenAPI 3.1](/openapi.json) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt