> ## Documentation Index > Fetch the complete documentation index at: https://docs.tented.ai/llms.txt > Use this file to discover all available pages before exploring further. # Preview an import > Parse the session's CSV and return everything needed to build the mapping step: the detected column headers, proposed column-to-field mappings (deterministic header matching plus AI-assisted suggestions), the catalog of available target fields (importable standard fields and your active custom fields), suggested new custom fields for unmapped columns (`field_creation_candidates`), a sample of rows, and validation issues found in that sample. No request body. Safe to call repeatedly — for example, after bulk-creating suggested custom fields via `POST /v1/contact-fields`, preview again to see the new fields mapped. `blocking_issues` must be resolved before executing: an import needs at least one column mapped to `email` or `phone` so contacts can be identified and deduplicated. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contacts/imports/{sessionId}/preview openapi: 3.1.0 info: title: Tented API version: 1.0.0 description: >- The Tented public API: generate, publish, and manage AI-built web pages (tents), and run the email platform — contacts, reusable emails, one-time blasts, and triggered flows. ## Authentication Authenticate every request with a workspace API key: `Authorization: Bearer `. Keys are created in **Workspace Settings → API Keys** and are scoped to a single workspace. ## Asynchronous work Tent generation, bulk creation, and email AI generation return `202 Accepted` immediately. Poll the corresponding status endpoint (`GET /v1/tents/{tentId}`, `GET /v1/bulk-jobs/{bulkJobId}`, `GET /v1/emails/{emailId}/generations/{generationId}`) — no more than every 10 seconds. ## Pagination Email listings use cursor pagination (`cursor`/`next_cursor`). Blast, flow, and member listings use page pagination (`page`/`limit` with a `pagination` object in the response). ## Conventions Request and response fields are snake_case, with two exceptions: analytics query parameters (`tentIdOrAlias`, `daysBack`) and segment rule trees (camelCase keys such as `listId` and `timeWindow`). contact: name: Tented Support email: support@tented.ai servers: - url: https://api.tented.ai description: Production security: - bearerAuth: [] tags: - name: Tents description: >- Create, edit, publish, and manage AI-generated pages, including asset uploads and bulk creation. - name: Analytics description: Traffic analytics for single tents and the whole workspace. - name: Contacts description: >- Batch create, update, and delete contacts. Up to 25 items per request with per-item results. - name: Emails description: >- Reusable email content: AI generation, direct HTML edits, plain-text control, and approval. - name: Email Blasts description: >- One-time sends to an audience: compose, schedule, track engagement, export recipients. - name: Triggered Flows description: >- Multi-step automations that enroll contacts on triggers and move them through a step graph. - name: Contact Imports - name: Contact Fields - name: Contact Lists - name: Email Templates - name: Tent Templates description: >- Reusable, AI-editable tent layouts. Create from HTML or an existing tent, iterate with AI, approve, and clone. Approved tent templates seed new tents. paths: /v1/contacts/imports/{sessionId}/preview: post: tags: - Contact Imports summary: Preview an import description: >- Parse the session's CSV and return everything needed to build the mapping step: the detected column headers, proposed column-to-field mappings (deterministic header matching plus AI-assisted suggestions), the catalog of available target fields (importable standard fields and your active custom fields), suggested new custom fields for unmapped columns (`field_creation_candidates`), a sample of rows, and validation issues found in that sample. No request body. Safe to call repeatedly — for example, after bulk-creating suggested custom fields via `POST /v1/contact-fields`, preview again to see the new fields mapped. `blocking_issues` must be resolved before executing: an import needs at least one column mapped to `email` or `phone` so contacts can be identified and deduplicated. operationId: preview-contact-import parameters: - name: sessionId in: path required: true schema: type: string format: uuid description: Import session ID from `POST /v1/contacts/imports`. responses: '200': description: Parsed preview with proposed mappings and sample validation issues. content: application/json: schema: $ref: '#/components/schemas/ContactImportPreview' '400': description: >- Bad request — the source file is unavailable (e.g. the presigned upload was never completed) or exceeds the 350 MB size limit. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing, malformed, revoked, or expired API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Not found — the import session does not exist in the workspace tied to your API key, or has expired (sessions are retained for 7 days). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ContactImportPreview: type: object properties: import_session_id: type: string format: uuid description: Import session ID. headers: type: array items: type: string description: Column headers detected in the CSV. proposed_mappings: type: array items: $ref: '#/components/schemas/ContactImportMapping' description: >- Proposed column-to-field mappings, one per header. Use these as the starting point for the execute call's `mappings`. unmapped_headers: type: array items: type: string description: 'Headers with no proposed target (`target_field: null`).' available_fields: type: object properties: standard: type: array items: $ref: '#/components/schemas/ContactImportAvailableField' description: Importable standard contact fields. custom: type: array items: $ref: '#/components/schemas/ContactImportAvailableField' description: Your workspace's active custom fields. required: - standard - custom description: Catalog of valid mapping targets. field_creation_candidates: type: array items: $ref: '#/components/schemas/ContactImportFieldCreationCandidate' description: Suggested new custom fields for unmapped columns. sample_rows: type: array items: type: object additionalProperties: type: string description: 'One row: header → cell value (always strings).' description: A sample of the file's first data rows. sample_issues: type: array items: $ref: '#/components/schemas/ContactImportFieldIssue' description: >- Validation issues found in the sample rows under the proposed mappings — a preview of the problems the full import would hit. blocking_issues: type: array items: type: object properties: code: type: string enum: - missing_identity_mapping description: Blocking issue code. message: type: string description: Human-readable explanation. required: - code - message description: >- Issues that must be resolved before execution — currently only `missing_identity_mapping`: no column maps to `email` or `phone`, so contacts cannot be identified. required: - import_session_id - headers - proposed_mappings - unmapped_headers - available_fields - field_creation_candidates - sample_rows - sample_issues - blocking_issues description: >- Preview of an import: detected headers, proposed mappings, available target fields, new-field suggestions, and sample validation issues. Error: type: object properties: error: type: string description: Human-readable error message. error_code: type: string description: >- Stable machine-readable error code (present on email, blast, flow, and related endpoints, e.g. `campaign_not_ready`, `generation_in_progress`). message: type: string description: Additional human-readable context (present on some tent endpoints). code: type: string description: >- Machine-readable code used by tent creation errors (e.g. `INVALID_PROMPT_INTENT`). details: type: object additionalProperties: true description: >- Additional error context. Validation errors include `issues`: an array of `{ path, message }` objects. limit: type: integer description: Plan limit that was hit (present on `429` publish-limit errors). current: type: integer description: >- Current usage against the limit (present on `429` publish-limit errors). required: - error description: >- Error response. All errors include `error`; the other fields vary by endpoint group. ContactImportMapping: type: object properties: header: type: string description: CSV column header this mapping applies to. target_field: type: - string - 'null' description: >- Target field `api_name` (e.g. `email`, `firstName`, or a custom field's `api_name`), `listIds` for list-membership columns, or `null` when the column is unmapped. target_kind: type: - string - 'null' enum: - standard - custom - membership - null description: >- Kind of target: `standard` (built-in contact field), `custom` (custom field), `membership` (the column contains contact list IDs to add the contact to), or `null` when unmapped. reason: type: string description: >- Why this mapping was proposed (e.g. exact header match, AI suggestion). source: type: string enum: - deterministic - llm - user description: >- How the mapping was produced: `deterministic` header matching, `llm` (AI-assisted), or `user` (previously approved). overwrite_behavior: type: string enum: - overwrite - skip_if_filled description: >- Per-column overwrite behavior when updating an existing contact. Omitted on proposed mappings — set it when executing. required: - header - target_field - target_kind - reason - source description: A proposed column-to-field mapping from the preview step. ContactImportAvailableField: type: object properties: api_name: type: string description: >- Stable field identifier used as a mapping `target_field` (e.g. `email`, `firstName`, or a custom field's `api_name`). display_name: type: string description: Human-readable label. type: type: string enum: - standard - custom description: >- `standard` for built-in contact fields, `custom` for workspace custom fields. value_type: type: string enum: - string - number - boolean - email - phone - date description: >- Value type. Standard fields may use `email`/`phone`; custom fields are `string`, `number`, `boolean`, or `date`. is_editable: type: boolean description: Whether values can be edited manually in the UI. Custom fields only. field_definition_id: type: string format: uuid description: Custom field definition ID. Custom fields only. status: type: string enum: - active - archived description: Field status. Custom fields only. management_mode: type: string enum: - org_managed - integration_managed description: >- Who owns the field: your workspace or a connected integration. Custom fields only. provenance_kind: type: string enum: - manual_ui - import_csv - integration description: How the field was created. Custom fields only. created_from_import_session_id: type: - string - 'null' description: >- Import session the field was created from, when `provenance_kind` is `import_csv`. Custom fields only. required: - api_name - display_name - type - value_type description: >- A field available as an import mapping target. Standard entries include only the first four properties; custom entries include the full definition metadata. ContactImportFieldCreationCandidate: type: object properties: header: type: string description: Unmapped CSV column this candidate would capture. suggested_display_name: type: string description: Suggested human-readable label for the new custom field. suggested_api_name: type: string description: Suggested `api_name` for the new custom field. suggested_value_type: type: string enum: - string - number - boolean - date description: Value type inferred from the column's sample values. confidence: type: string enum: - low - medium - high description: Confidence in the suggestion. sample_values: type: array items: type: string description: Sample values from the column. reason: type: string description: Why this column looks like a new custom field. conflicts: type: array items: type: object properties: kind: type: string enum: - archived_existing - duplicate_suggestion description: >- `archived_existing`: an archived custom field already uses this name — restore it instead of creating a new one. `duplicate_suggestion`: another candidate in this preview resolves to the same name. resolution: type: string enum: - restore_existing - resolve_duplicate description: Suggested resolution. existing_field_definition_id: type: string format: uuid description: ID of the archived field (for `archived_existing`). existing_field_display_name: type: string description: Display name of the archived field (for `archived_existing`). conflict_key: type: string description: >- Shared key that groups duplicate suggestions (for `duplicate_suggestion`). required: - kind - resolution description: Conflict blocking automatic creation. description: >- Empty when the candidate is ready to create as-is. Multiple conflicts can apply to the same candidate. required: - header - suggested_display_name - suggested_api_name - suggested_value_type - confidence - sample_values - reason - conflicts description: >- A suggested new custom field for an unmapped column. Create accepted candidates via `POST /v1/contact-fields`, then pass their IDs to execute as `created_field_definition_ids`. ContactImportFieldIssue: type: object properties: row_number: type: integer description: >- 1-based CSV line number, counting the header row as line 1 (the first data row is 2). header: type: string description: CSV column header the issue occurred in. target_field: type: string description: Target field `api_name` the column maps to. code: type: string enum: - invalid_email - invalid_phone - invalid_boolean - invalid_number - invalid_date - invalid_value_too_long - invalid_list_id - unknown_list_id - dynamic_list_not_supported - system_list_not_writable - missing_identity_mapping description: Machine-readable issue code. message: type: string description: Human-readable explanation. value: type: string description: The offending cell value. required: - row_number - header - target_field - code - message - value description: A field-level validation issue for one cell of the import. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Workspace API key, e.g. `Authorization: Bearer tented_...`. Create keys in Workspace Settings → API Keys. ````