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.

Proposed mappings never send two columns to the same field: a header-name match wins over an AI suggestion, then the earlier column wins, and the other column is left unmapped (its reason names the column that claimed the field) so it can be offered in field_creation_candidates.

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.

POST /v1/contacts/imports/{sessionId}/preview

Preview an import

cURL

curl --request POST \
  --url https://api.tented.ai/v1/contacts/imports/{sessionId}/preview \
  --header 'Authorization: Bearer <token>'

200

{
  "import_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "headers": [
    "<string>"
  ],
  "proposed_mappings": [
    {
      "header": "<string>",
      "target_field": "<string>",
      "target_kind": "standard",
      "reason": "<string>",
      "source": "deterministic",
      "overwrite_behavior": "overwrite"
    }
  ],
  "unmapped_headers": [
    "<string>"
  ],
  "available_fields": {
    "standard": [
      {
        "api_name": "<string>",
        "display_name": "<string>",
        "type": "standard",
        "value_type": "string",
        "is_editable": true,
        "field_definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "status": "active",
        "management_mode": "org_managed",
        "provenance_kind": "manual_ui",
        "created_from_import_session_id": "<string>"
      }
    ],
    "custom": [
      {
        "api_name": "<string>",
        "display_name": "<string>",
        "type": "standard",
        "value_type": "string",
        "is_editable": true,
        "field_definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "status": "active",
        "management_mode": "org_managed",
        "provenance_kind": "manual_ui",
        "created_from_import_session_id": "<string>"
      }
    ]
  },
  "field_creation_candidates": [
    {
      "header": "<string>",
      "suggested_display_name": "<string>",
      "suggested_api_name": "<string>",
      "suggested_value_type": "string",
      "confidence": "low",
      "sample_values": [
        "<string>"
      ],
      "reason": "<string>",
      "conflicts": [
        {
          "kind": "archived_existing",
          "resolution": "restore_existing",
          "existing_field_definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "existing_field_display_name": "<string>",
          "conflict_key": "<string>"
        }
      ]
    }
  ],
  "sample_rows": [
    {}
  ],
  "sample_issues": [
    {
      "row_number": 123,
      "header": "<string>",
      "target_field": "<string>",
      "code": "invalid_email",
      "message": "<string>",
      "value": "<string>"
    }
  ],
  "blocking_issues": [
    {
      "code": "missing_identity_mapping",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.

Path Parameters

sessionId · string<uuid> · required

Import session ID from POST /v1/contacts/imports.

Response

200

application/json

Parsed preview with proposed mappings and sample validation issues.

Preview of an import: detected headers, proposed mappings, available target fields, new-field suggestions, and sample validation issues.

import_session_id · string<uuid> · required

Import session ID.

headers · string[] · required

Column headers detected in the CSV.

proposed_mappings · object[] · required

Proposed column-to-field mappings, one per header. Use these as the starting point for the execute call's mappings.

Show child attributes

unmapped_headers · string[] · required

Headers with no proposed target (target_field: null).

available_fields · object · required

Catalog of valid mapping targets.

Show child attributes

field_creation_candidates · object[] · required

Suggested new custom fields for unmapped columns.

Show child attributes

sample_rows · object[] · required

A sample of the file's first data rows.

Show child attributes

sample_issues · object[] · required

Validation issues found in the sample rows under the proposed mappings — a preview of the problems the full import would hit.

Show child attributes

blocking_issues · object[] · required

Issues that must be resolved before execution — currently only missing_identity_mapping: no column maps to email or phone, so contacts cannot be identified.

Show child attributes