Upload CSV file and generate AI mappings

Uploads a CSV file and automatically creates an import with AI-powered field mapping suggestions.

What this does: This is the first step in the import workflow. When you upload a CSV file, the system:

Parses the CSV file and extracts column metadata (names, data types, sample values)
Stores the file data and first 10 sample rows for preview
Uses AI to analyze the CSV structure and suggest field mappings
Generates mapping suggestions for supported entity types (Employee, Organization, Project, Task, etc.)
Returns the import details with suggested mappings ready for review

Supported Entity Types:

Employee: Import employee data (name, email, role, etc.)
Organization: Import organization/client data
OrganizationMember: Import organization membership relationships
Project: Import projects with custom fields support
Task: Import tasks with custom fields support
TaskComment: Import task comments

File Requirements:

File must be CSV format (text/csv, application/csv, or text/plain MIME types)
First row should contain column headers
File will be parsed with automatic delimiter detection

AI Mapping Features:

Automatically detects which columns map to which entity fields
Suggests value mappings for enums (e.g., “Manager” → “manager” role)
Handles custom fields for Projects and Tasks
Identifies relationships and dependencies (e.g., Organization for OrganizationMember)

Next Steps: After upload, review the suggested mappings using GET /{importId}, then:

Modify mappings if needed using PUT /{importId}/mappings
Run a dry-run using POST /{importId}/dry-run to preview results
Execute the import using POST /{importId}/execute to persist data

Note: The AI mapping may not be perfect - always review and test with dry-run before executing.

POST/imports-management/upload

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredmultipart/form-data

CSV file to upload

filestring

CSV file (text/csv, application/csv, or text/plain)

Responses

200CSV file uploaded and AI mappings generated successfully

aiMappingSuccessbooleanrequired

Indicates whether AI mapping generation completed successfully. If false, mappings array may be empty or incomplete, and you may need to manually configure mappings.

columnCountnumberrequired

Total number of columns detected in the CSV file

columnsany[]required

Metadata for each column in the CSV file, including column UUID (use this in mappings), name, detected data type, and sample values. Column UUIDs are required when creating field mappings.

fileNamestringrequired

Original file name of the uploaded CSV file

importIdstringrequired

Unique identifier (UUID) for the newly created import. Use this ID to fetch details, update mappings, or execute the import.

mappingsobject[]required

AI-generated mapping suggestions in AI format. Each mapping specifies an entity type (e.g., "Employee", "Project") and suggested field mappings from CSV columns to entity fields. Review and modify these before executing the import.

Show properties

Array of object

customLookupFieldsstring[]

Optional array of field names (including custom fields like "customField_abc123") to use for finding existing records. If not provided, uses entity default lookup fields.

fieldsobject

Field mappings object. Keys are entity field names, values contain mapTo (column UUID), optional defaultValue, and optional valueMappings for enums

typestring

Entity type to import: "Employee", "Organization", "OrganizationMember", "Project", "Task", or "TaskComment"

rowCountnumberrequired

Total number of data rows in the CSV file (excluding header row)

sampleRowsany[]required

First 10 rows of data from the CSV file for preview. Useful for understanding the data structure and validating mappings.

statusstringrequired

Current status of the import. Will be "Uploaded" immediately after upload, indicating the import is ready for mapping configuration.

Allowed:UploadedProcessingCompletedFailed

400Invalid file type or CSV parsing error

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X POST "https://leadtime.app/api/public/imports-management/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -d '{
  "file": "string"
}'

const response = await fetch("https://leadtime.app/api/public/imports-management/upload", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "multipart/form-data"
  },
  body: JSON.stringify({
  "file": "string"
})
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/imports-management/upload",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "multipart/form-data"
    },
    json={
  "file": "string"
},
)

Response

{
  "aiMappingSuccess": true,
  "columnCount": 12,
  "columns": [
    null
  ],
  "fileName": "employees.csv",
  "importId": "d2ee76e3-95d7-4b98-8d5d-98dc1fb79364",
  "mappings": [
    {
      "customLookupFields": [
        "string"
      ],
      "fields": {},
      "type": "string"
    }
  ],
  "rowCount": 150,
  "sampleRows": [
    null
  ],
  "status": "Uploaded"
}