The ImportDefinition object defines a reusable pattern of import options. For example, you could create an import definition to upload Subscribers.csv every day into the Customers list to prevent having to re-enter the same parameters every day.

If you import information to a data extension, you must create a data extension object and set the ObjectID property or customer key on the data extension object. You must then set the DestinationObject property to that object. If you are importing to a list, you must create a list object, set an ID property, and set the DestinationObject property to that object. You must specify the ID property for a list. Imports don't currently support the use of ObjectID or CustomerKey when importing to a list.

You can specify what character encoding you wish to use with your imports, but this specification applies to all imports in an account and can only be enabled by your Account Executive.

  • To create an ImportDefinition where the destination object is a list, you need the Email | Subscribers | List | Import Subscribers permission.
  • To create or update an ImportDefinition where the destination object is a data extension, you need the Email | Subscribers | Data Extension | Import and Manage Data permissions.
  • To create or update an ImportDefinition where the destination object is a list and the list ID is the All Subs List ID, you need the Email | Subscribers | All Subscribers | Import Subscribers and View permissions.
NameData TypeDescription
AllowErrorsxsdSpecifies whether an import continues after an error occurs. A value of true permits the import process to continue, and a value of false stops the import process after the first error.
AutoGenerateDestinationImportDefinitionAutoGenerateDestinationSpecifies the properties of the destination to be generated automatically during an import.
ClientClientIDSpecifies the account ownership and context of an object.
ControlColumnxsdSpecifies the column name in which to find control values as part of an import (use when the value ofImportDefinitionUpdateTypeis ColumnBased).
ControlColumnActionsImportDefinitionColumnBasedAction[]Specifies the control column actions to apply to an import.
ControlColumnDefaultActionImportDefinitionColumnBasedActionTypeDefines default control column action to take as part of an import definition. Valid values include:
  • AddAndUpdate
  • AddButDoNotUpdate
  • Delete
  • Skip
  • UpdateButDoNotAdd
CorrelationIDxsdIdentifies correlation of objects across several requests.
CreatedDatexsdRead-only date and time of the object's creation.
CustomerKeyxsdUser-supplied unique identifier for an object within an object type. This property corresponds to the external key assigned to an object.
DateFormattingLocaleLocaleSpecifies how dates are formatted in import data; used to ensure the data is interpreted correctly when it is being loaded.
DeleteFileBooleanIndicates whether the call deletes the file used in the import once the process completes.
DelimiterxsdSpecifies the delimiter used as part of an import definition.
DescriptionxsdDescribes and provides information regarding the object.
DestinationObjectAPIObjectSpecifies the destination of an import.
DestinationTypexsdReserved for future use.
EndOfLineRepresentationxsdSpecifies the line-ending character(s) used in delimited files to be imported.
FieldMappingTypeImportDefinitionFieldMappingTypeDefines how fields are mapped within an import definition. Valid values include:
  • InferFromColumnHeadings
  • MapByOrdinal
  • ManualMap
FieldMapsFieldMap[]Specifies the mapping of fields to columns in a file.
FileSpecxsdDefines the file-naming pattern associated with an activity (valid substitutions include%%YEAR%%, %%MONTH%%, and %%DAY%%).
FileTypeFileTypeSpecifies column delimiter of a file. Valid values include:
  • CSV
  • TAB
  • Other
FilterxsdSpecifies filter to apply to retrieve.
HeaderLinesxsdSpecifies the number of header lines in the file to ignore.
IDxsdRead-only identifier for an object. Some objects use the ObjectID property as a unique ID.
InteractionObjectIDxsdReturns associated ID for activities within the asynchronous process of the overall conversation or program.
KeywordxsdReserved for future use.
MaxFileAgexsdSpecifies the age of the oldest file to be included in an import definition. Any files older than the maximum age are not included in the import definition.
MaxFileAgeScheduleOffsetxsdSpecifies an offset in hours to associate with a file age for accomodating timezone differences. This time represents the maximum allowable difference between the scheduled time and the time the import definition actually accesses the file to be imported.
MaxImportFrequencyxsdSpecifies the number of hours to wait before allowing a file to be imported again. This property prevents an import definition run within a program from executing if a specified number of hours have passed since the program began.
ModifiedDateNullable`1Indicates the last time object information was modified.
NamexsdName of the object or property.
NotificationAsyncResponseSpecifies the email address to which to send a notification.
NullRepresentationxsdDefines character used to represent a null value during an import.
ObjectIDxsdSystem-controlled, read-only text string identifier for object.
ObjectStatexsdReserved for future use.
OwnerOwnerDescribes account ownership of subscriber in an on-your-behalf account.
PartnerKeyxsdUnique identifier provided by partner for an object. This property is accessible only via API.
PartnerPropertiesAPIProperty[]A collection of metadata supplied by the client and stored by the system. These properties are accessible only via API.
RetrieveFileTransferLocationFileTransferLocationSpecifies the file transfer location to contain the file.
SourceObjectAPIObjectSpecifies source of the import.
StandardQuotedStringsxsdSpecifies whether standard quoted strings are used as part of an import definition. A true value indicates standard quoted strings are used in an import definition.
SubscriberImportTypeImportDefinitionSubscriberImportTypeSpecifies the subscriber import type for an import definition. Valid values include Email and SMS.
SubscriptionDefinitionIdxsdIdentifies subscription to which the import definition is associated.
UpdateTypeImportDefinitionUpdateTypeIndicates update type associated with an import definition. Valid values include:
  • AddAndUpdate
  • AddAndDoNotUpdate
  • UpdateButDoNotAdd
  • Merge
  • Overwrite
  • ColumnBased