Zum Inhalt springen
Leadtime
Deutsch
EnglishDeutschNicht übersetzt
Esc
↑↓navigieren↵öffnen⌘Jvorschau

Update all import mappings in bulk

Replaces all field mappings for an import in a single request. This is the primary way to configure how CSV columns map to entity fields.

What this does:

  • Deletes all existing mappings for the import
  • Creates new mappings from your request
  • Automatically adds dependency mappings (e.g., if you map OrganizationMember, it will also create Organization mapping if needed)
  • Validates that all column IDs exist in the import
  • Triggers re-validation of all mappings
  • Returns the updated mappings in AI format

AI Mapping Format: Each mapping specifies an entity type and its field mappings:

{
  "mappings": [
    {
      "type": "Employee",
      "fields": {
        "firstName": { "mapTo": "column-uuid-here" },
        "lastName": { "mapTo": "column-uuid-here" },
        "email": { "mapTo": "column-uuid-here" },
        "role": {
          "mapTo": "column-uuid-here",
          "valueMappings": { "Manager": "manager", "Developer": "developer" }
        }
      },
      "customLookupFields": ["email"]  // optional: fields to use for finding existing records
    }
  ]
}

Field Mapping Properties:

  • mapTo: Required - The UUID of the CSV column (get column IDs from GET /{importId})
  • defaultValue: Optional - Default value if CSV cell is empty
  • valueMappings: Optional - Map CSV values to entity values (e.g., “Yes” → true, “Manager” → “manager”)

Custom Lookup Fields: Specify which fields should be used to find existing records for updates. If a record matches on these fields, it will be updated; otherwise, a new record will be created.

  • Can include both built-in fields (e.g., “email”, “firstName”) and custom fields (e.g., “customField_abc123”)
  • If not specified, uses the entity’s default requiredToUpdate fields
  • Example: Use “email” for Employees, or a custom “externalId” field for Projects

Important Notes:

  • mapTo must be a column UUID from the import (get from GET /{importId} response), not a column name
  • All column IDs must exist in the import
  • Dependencies are automatically created (e.g., Organization for OrganizationMember, Project for Task)
  • Custom fields are referenced as customField_{fieldId} in field names
  • After updating, run a dry-run to validate mappings before execution
PUT/imports-management/{importId}/mappings
Authorization
AuthorizationOAuth2 access token · headerrequired
Scopes:api:write
or
AuthorizationBearer token (JWT) · headerrequired
Path parameters
importIdstringrequired

Unique identifier of the import

Query parameters
fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull
Header parameters
LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full
Request body
requiredapplication/json
mappingsobject[]required

Array of mapping configurations in AI format. Each mapping specifies an entity type and how CSV columns map to entity fields. This replaces all existing mappings for the import.

Show properties
Array of object
customLookupFieldsstring[]

Optional array of field names to use for finding existing records. Can include built-in fields (e.g., "email", "firstName") or custom fields (e.g., "customField_abc123"). If a record matches on these fields, it will be updated; otherwise, a new record will be created. If not provided, uses the entity's default requiredToUpdate fields.

fieldsobject

Field mappings object. Keys are entity field names (or "customField_{fieldId}" for custom fields). Values are objects with: mapTo (required, CSV column UUID), defaultValue (optional), and valueMappings (optional, for enum conversions).

typestring

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

Responses
200

Mappings updated successfully

mappingsany[]required

Updated mappings in AI format, including any automatically added dependency mappings (e.g., Organization mapping if OrganizationMember was specified). Use these mappings to verify the final configuration.

successbooleanrequired

Indicates whether the mapping update was successful. If true, all mappings have been saved and validated.

400

Invalid mapping structure or column IDs

401

Unauthorized - Invalid or missing authentication token

403

Forbidden - Insufficient API scopes or permissions

404

Import not found

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X PUT "https://leadtime.app/api/public/imports-management/d2ee76e3-95d7-4b98-8d5d-98dc1fb79364/mappings" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mappings": [
    {
      "customLookupFields": [
        "email"
      ],
      "fields": {
        "email": {
          "mapTo": "b4gg98g5-17f9-6d10-0f7f-10fe3hd91586"
        },
        "firstName": {
          "mapTo": "d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"
        },
        "lastName": {
          "mapTo": "a3ff87f4-06e8-5c09-9e6e-09ed2gc80475"
        }
      },
      "type": "Employee"
    }
  ]
}'
Response
{
  "mappings": [],
  "success": true
}