--- schema_version: "1" id: d9d9299336e43d51a8a4de2a6d0ef4d4136ae5af8aa931f6626b3b7f337e7798 title: Data Extension Imports collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc-import_job_api.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-import_job_api source_site: developer.salesforce.com content_type: documentation content_hash: 9247eb49acd4ae6dd29957074032f648abf1e552c05a932c8750cace86457b01 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Data Extension Imports # Data Extension Imports Import data from a file transfer location into a data extension without creating an import definition. You can import data from a pre-signed file location such as Amazon Web Services (AWS) or Microsoft Azure without configuring a file transfer location. This table lists the use cases that the API supports. | Supported Use Case | HTTP Verb | Endpoint | | --- | --- | --- | | [Queue and start a one-time data import](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Queue%2Band%2Bstart%2Ba%2Bone-time%2Bdata%2Bimport) | POST | /data/v1/async/import | | [Get status of a one-time data import](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Get%2Bstatus%2Bof%2Ba%2Bone-time%2Bdata%2Bimport) | GET | /data/v1/async/import/{id}/summary | | [Get validation summary of a one-time data import](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Get%2Bvalidation%2Bsummary%2Bfor%2Ba%2Bdata%2Bimport) | GET | /data/v1/async/import/{id}/validationsummary | | [Get validation details of a one-time data import](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Get%2Bvalidation%2Bdetails%2Bof%2Ba%2Bone-time%2Bdata%2Bimport) | GET | /data/v1/async/import/{id}/validationresult | ### Prerequisites If you receive `errorcode 20002 - Insufficient privileges to complete this action`, verify each of these requirements. After verifying all of them, if the error persists, contact Salesforce Customer Support. This error code can also indicate a transient platform issue. **Installed package scopes.** Your installed package must grant all of the following scopes. Every scope is required for every call to `POST /data/v1/async/import`, regardless of whether the source is a file-transfer location or a pre-signed URL. | Category | Scope label in the UI | OAuth scope string | | --- | --- | --- | | Automation > Automations | Read | `automations_read` | | Automation > Automations | Write | `automations_write` | | Automation > Automations | Execute | `automations_execute` | | Data > Data Extensions | Read | `data_extensions_read` | | Data > Data Extensions | Write | `data_extensions_write` | | Data > File Locations | Read | `file_locations_read` | | Data > File Locations | Write | `file_locations_write` | Configure scopes at **Setup > Apps > Installed Packages**, open the package, and update the API Integration component. If you pass a `scope` parameter when you request an access token, make sure it doesn't narrow the granted scopes. To verify which scopes a given access token carries, inspect the `scope` field in the token response. **Role-level data extension permissions.** The run-as user for the installed package must have a role that grants **Email Studio > Subscribers > Data Extensions**: View, Update, and Manage Data. The standard Marketing Cloud Channel Manager role bundles these permissions. To compare a custom role against the standard role, see [Marketing Cloud Roles](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_marketing_cloud_roles.htm&type=5). **Role-level Import activity permission.** The same role must include the Import activity permission. To turn on this permission, click **Email > Interactions > Activities > Import**. **Shared data extension access.** If the target data extension is shared from another business unit, the business unit running the import must have Read, Update, Insert, Delete, and Export permissions on the shared data extension. To configure sharing across business units, click **Email Studio > Subscribers > Shared Data Extensions**, select the data extension, and open the **Permissions** tab. For details, see [Shared Data Extension Permissions](https://help.salesforce.com/s/articleView?id=sf.mc_es_permissions_shared_data_extensions.htm&type=5). **Run-as user.** The run-as user for the installed package must be active and assigned to the business unit that the import targets. Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant: **Version:** 1 ## Servers * `https://{subdomain}.rest.marketingcloudapis.com` * `subdomain (default N/A) The unique API subdomain for your Marketing Cloud Engagement tenant. Find this value in the Installed Packages section of Marketing Cloud Engagement Setup.` ## Operations ### POST Queue and start a one-time import into a data extension without creating an import definition. `POST /data/v1/async/import` Operation ID: `Queue and start a one-time data import`. Perform a file-based import without creating an import definition. Store the source file in an active file transfer location, or provide a pre-signed URL. The source file can be on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, or an external SFTP server. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token used to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Queue and start a one-time import of data into a data extension without creating an import definition. Media type: `application/json`. Schema: `importJobRequestBody`. _Example: Perform an import from a file transfer location_ ``` { "source": { "fileInfo": { "specifier": "sample.csv", "contentType": "CSV", "standardQuotedStrings": true } }, "target": { "type": "DataExtension", "key": "S3_Test_1000_Rows", "updateType": "Overwrite" }, "mapping": { "allowErrors": true, "fieldMappingType": "InferFromColumnHeadings" }, "transport": { "key": "FILE_LOCATION_KEY" } } ``` _Example: Perform an import with a pre-signed URL_ ``` { "source": { "fileInfo": { "specifier": "https://mcde-dev.s3.amazonaws.com/siva.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=REDACTED_AWS_ACCESS_KEY_ID/20231016/us-east-1/s3/aws4_request&X-Amz-Date=20231016T161159Z&X-Amz-Expires=3597&X-Amz-SignedHeaders=host&X-Amz-Signature=REDACTED_AWS_SIGNATURE", "contentType": "CSV", "standardQuotedStrings": true } }, "target": { "type": "DataExtension", "key": "S3_Test_1000_Rows", "updateType": "Overwrite" }, "mapping": { "allowErrors": true, "fieldMappingType": "InferFromColumnHeadings" }, "transport": { "key": "FILE_LOCATION_KEY" } } ``` _Example: Perform a multi-file import from a file transfer location_ ``` { "source": { "fileInfo": { "specifier" : "Imports_Tests/DATA", "contentType" : "OTHER", "hasMultipleFiles" : true, "standardQuotedStrings": true, "fieldDelimiter":"¶" }}, "target": { "type": "DataExtension", "key": "0C695893-C7CF-4265-B953-FCE41FDAD5F9", "updateType": "Overwrite" }, "mapping": { "allowErrors": true, "fieldMappingType": "InferFromColumnHeadings" }, "transport": { "key": "FILE_LOCATION_KEY" } } ``` _Example: Perform an import with Column-based update type_ ``` { "source": { "fileInfo": { "specifier": "Activation/2005418/CDPTestData.csv", "contentType": "Other", "hasMultipleFiles": false, "standardQuotedStrings": true, "fieldDelimiter": " " } }, "target": { "type": "DataExtension", "key": "Async_API_DE", "updateType": "ColumnBased", "controlColumn": "ControlColumn", "controlColumnDefaultAction": "Delete", "controlColumnActions": null }, "transport": { "key": "FILE_LOCATION_KEY" }, "mapping": { "allowErrors": true, "fieldMappingType": "InferFromColumnHeadings" } } ``` #### Responses * **200** The request to create an import job was successful. Media type: `application/json`. Schema: `createImportJobResponseBody`. _Example_ ``` { "id": 51593, "requestId": "cb42eea2-f986-4d2f-bed6-87f3dfcc9058", "resultMessages": [] } ``` * **400** The request failed because the request body is invalid. Media type: `application/json`. Schema: `createImportJobFailureResponseBody`. _Example_ ``` { "requestId": "60cca1da-f4d1-494f-886e-dc7fe742f663", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "resultCode": "MissingRequiredImportObjectProperty", "message": "Missing required property for object: Import, ImportSource cannot be null or empty." }, { "resultType": "Validation", "resultClass": "Error", "resultCode": "MissingRequiredImportObjectProperty", "message": "Missing required property for object: Import, ImportTarget cannot be null or empty." }, { "resultType": "Validation", "resultClass": "Error", "resultCode": "MissingRequiredImportObjectProperty", "message": "Missing required property for object: Import, Transport cannot be null or empty." }, { "resultType": "Validation", "resultClass": "Error", "resultCode": "MissingRequiredImportObjectProperty", "message": "Missing required property for object: Import, Mapping cannot be null or empty." } ] } ``` * **401** Indicates that the API couldn’t authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. A 403 with `errorcode 20002` means that the caller is missing one of the required permissions. To resolve this error, see [Prerequisites in Data Extension Imports](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Summary#prerequisites). Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "MCMS_UTM_Authorization_InsufficientPrivileges: Insufficient privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Internal Server Error" } ``` ### GET Returns the status of a queued data import, including the final number of imported rows and the import status (\`Success\` or \`Error\`). `GET /data/v1/async/import/{id}/summary` Operation ID: `Get status of a one-time data import`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token used to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, integer, required) The unique identifier of the one-time data import. #### Responses * **200** The request to get the status of a queued data import was successful. If the import ID is found, the response includes the import summary. If the import ID isn't found, the response omits the `summary` object and includes details in the `resultMessages` array. Media type: `application/json`. Schema: `importSummaryResponseBody`. _Example: Success Response_ ``` { "summary": { "duplicateRows": 0, "restrictedRows": 0, "endDate": "10/16/2023 10:22:26 AM", "errors": 0, "id": 15445111, "importStatus": "Success", "importId": "ac247ef5-b6c8-4ab1-b1d0-69f6a63ce33a", "startDate": "10/16/2023 10:22:24 AM", "successfulRows": 0, "targetId": "48D72A0D-B436-EE11-813D-1402EC6B95BC", "targetKey": "", "targetUpdateType": "Data Extension", "totalRows": 1 }, "requestId": "a7d17c4d-ab9e-400e-929b-bb4c7a362992", "resultMessages": [] } ``` _Example: Error Response_ ``` { "requestId": "8b3b9b15-f461-4c90-9ded-390880650746", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "ImportSummaryNotFound", "message": "ImportSummary cannot be found for Id: 91918282." } ] } ``` * **401** Indicates that the API couldn’t authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. A 403 with `errorcode 20002` means that the caller is missing one of the required permissions. To resolve this error, see [Prerequisites in Data Extension Imports](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Summary#prerequisites). Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "MCMS_UTM_Authorization_InsufficientPrivileges: Insufficient privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Internal Server Error" } ``` ### GET Retrieve a list of row-level validation errors that occurred during an import. Use this method after an import finishes to see the total number of failed rows. `GET /data/v1/async/import/{id}/validationsummary` Operation ID: `Get validation summary for a data import`. Tags: Get import row-level validation summary by taskId. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token used to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, integer, required) The unique identifier of the one-time data import. #### Responses * **200** The request to get the validation summary of a data import was successful. Media type: `application/json`. Schema: `importValidationSummarySuccessResponseBody`. _Example_ ``` { "id": 7033005, "importValidationSummary": [ { "validationErrorType": "RequiredField", "validationErrorCodeId": 6, "errorsCount": 115173 }, { "validationErrorType": "InvalidFieldCount", "validationErrorCodeId": 68, "errorsCount": 1 }, { "validationErrorType": "InvalidEmailAddress", "validationErrorCodeId": 18, "errorsCount": 9 } ], "requestId": "cbeb58d0-64d5-4db7-a9d8-77a8f4bc0905", "resultMessages": [] } ``` * **400** The request failed because the ID is invalid. Media type: `application/json`. Schema: `importValidationSummaryFailureResponseBody`. _Example_ ``` { "taskId": 0, "requestId": "24406701-1603-4b92-b437-852de514c786", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "resultCode": "ImportValidationSummaryInvalidId", "message": "Invalid id for Import Validation Summary." } ] } ``` * **401** Indicates that the API couldn’t authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. A 403 with `errorcode 20002` means that the caller is missing one of the required permissions. To resolve this error, see [Prerequisites in Data Extension Imports](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Summary#prerequisites). Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "MCMS_UTM_Authorization_InsufficientPrivileges: Insufficient privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Internal Server Error" } ``` ### GET Get import row-level validation details by ID. `GET /data/v1/async/import/{id}/validationresult` Operation ID: `Get validation details of a one-time data import`. Returns details of row-level validation errors that occurred during an import. Use this method after the import job finishes to see how many rows failed to import. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token used to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, integer, required) The unique identifier of the one-time data import. #### Responses * **200** The request to get the validation details of a data import was successful. Media type: `application/json`. Schema: `importValidationDetailsResponseBody`. _Example_ ``` { "id": 7033005, "page": 1, "pageSize": 50, "count": 115183, "items": [ { "rowId": 0, "validationErrorType": "RequiredField", "validationErrorCodeId": 6, "validationErrorDetails": "first_connection_at" }, { "rowId": 1, "validationErrorType": "RequiredField", "validationErrorCodeId": 6, "validationErrorDetails": "first_connection_at" }, { "rowId": 5, "validationErrorType": "RequiredField", "validationErrorCodeId": 6, "validationErrorDetails": "first_connection_at" }, { "rowId": 6, "validationErrorType": "RequiredField", "validationErrorCodeId": 6, "validationErrorDetails": "first_connection_at" } ] } ``` * **401** Indicates that the API couldn’t authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. A 403 with `errorcode 20002` means that the caller is missing one of the required permissions. To resolve this error, see [Prerequisites in Data Extension Imports](/docs/marketing/marketing-cloud/references/mc-import_job_api?meta=Summary#prerequisites). Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "MCMS_UTM_Authorization_InsufficientPrivileges: Insufficient privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Internal Server Error" } ``` ## Schemas ### importJobRequestBody Request body. * `importJobRequestBody` (_object_) Includes all fields of `fileInfo`, `target`, `mapping`, `transport`. ### createImportJobResponseBody * `id` (_integer_) The unique identifier of the import job. Use this value to retrieve the status of the import job. * `requestId` (_string_) A unique identifier for the request. * `resultMessages` (_array of resultMessages_) A list of messages related to the request. This list is typically empty in a successful response. ### createImportJobFailureResponseBody * `requestId` (_string_) A unique identifier for the request. * `resultMessages` (_array of resultMessages_) A list of messages related to the request. ### httpErrorResponseBody * `documentation` (_string_) Contains a link to the [Marketing Cloud Engagement developer documentation page about handling REST API errors](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm). * `errorcode` (_integer_) The error code. In some situations, this value can be 0. * `message` (_string_) The error message. ### mceErrorResponseBody * `documentation` (_string_) An empty string. * `errorcode` (_integer_) An internal error code. For a complete list of error codes, see [Handle Errors in REST API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/error-handling.html). * `message` (_string_) The error message. ### importSummaryResponseBody * `summary` (_object_) An object that contains information about the import job. * `duplicateRows` (_integer_) Number of duplicate rows. * `restrictedRows` (_integer_) Number of restricted rows. * `endDate` (_string_) The date and time the import job finished. * `errors` (_integer_) Number of errors. * `id` (_integer_) The unique identifier of the import job. * `importStatus` (_string_) The status of the import job. * `importId` (_string_) The unique identifier of the import job. * `startDate` (_string_) The date and time the import job started. * `successfulRows` (_integer_) Number of successful rows. * `targetId` (_string_) The unique identifier of the target data extension. * `targetKey` (_string_) The external key of the target data extension. * `targetUpdateType` (_string_) The type of import operation that was performed on the target data extension. * `totalRows` (_integer_) Total number of rows. * `requestId` (_string_) A unique identifier for the request. * `resultMessages` (_array of resultMessages_) A list of messages related to the request. This list is typically empty in a successful response. ### importValidationSummarySuccessResponseBody * `id` (_integer_) The unique identifier of the import job that the validation summary was generated for. * `importValidationSummary` (_array of object_) A list of validation errors. * `validationErrorType` (_string_) The type of validation error. * `validationErrorCodeId` (_integer_) The ID of the validation error. * `errorsCount` (_integer_) The number of errors that occurred. * `requestId` (_string_) A unique identifier for the request to retrieve the validation summary. * `resultMessages` (_array of resultMessages_) A list of messages related to the request. ### importValidationSummaryFailureResponseBody * `taskId` (_integer_) The unique identifier of the import job. * `requestId` (_string_) A unique identifier for the request. * `resultMessages` (_array of resultMessages_) A list of messages related to the request. ### importValidationDetailsResponseBody * `id` (_integer_) The unique identifier of the import job. * `page` (_integer_) The page number of the results. * `pageSize` (_integer_) The number of items per page of results. * `count` (_integer_) The total number of results. * `items` (_array of object_) A list of validation details. * `rowId` (_integer_) The row number where the validation error occurred. * `validationErrorType` (_string_) The type of validation error. * `validationErrorCodeId` (_integer_) An error code that corresponds to the validation error type. * `validationErrorDetails` (_string_) The field that caused the validation error. For example, if a required field is missing, this field contains the name of the missing field. ### fileInfo Defines the source file details for an import. * `specifier` (_string_, required) Name of the source file (compressed or uncompressed). For multiple files, specify the folder name instead. Example: `sample.csv`. * `contentType` (_string_, required) Indicates how the content is delimited. Example: `[CSV,TAB,OTHER]`. * `hasMultipleFiles` (_string_, required) Indicates whether the specifier has more than one file to import. Defaults to `false`. Example: `[true,false]`. * `standardQuotedStrings` (_string_) Indicates if the import respects double quotes (") as a text delimiter. Example: `[true,false]`. ### target Specifies the destination details for an import. * `type` (_string_, required) The type of the object being imported into. The only supported value is DataExtension. Example: `DataExtension`. * `key` (_string_, required) The unique (customerKey) reference of the data extension. Example: `DE_Customer_Key`. * `updateType` (_string_, required) The type of import operation to perform on the destination data extension. Example: `[Overwrite, AddAndUpdate, AddAndDoNotUpdate, UpdateButDoNotAdd, ColumnBased]`. * `controlColumn` (_string_) Column name in the source file that controls the row-level action—for example, `add`, `delete`, or `update`. Example: `[Action_Column]`. * `controlColumnDefaultAction` (_string_) Default action on a row when you don't specify an explicit action code. Example: `[Delete, AddAndUpdate]`. ### mapping Defines the field mapping for an import. * `allowErrors` (_boolean_, required) Indicates whether the import continues past row-level errors. Defaults to `true`. Example: `[true, false]`. * `fieldMappingType` (_string_, required) Indicates the type of field mapping. Example: `[InferFromColumnHeadings, MapByOrdinal, ManualMap]`. ### transport Defines the file transfer location details. * `key` (_string_, required) The external key of an active file transfer location. Create a file location on the **Data Management** | **File Locations** page in Setup. Example: `FILE_LOCATION_KEY`. ### resultMessages * `resultType` (_string_) The type of error. * `resultClass` (_string_) The class of the result. * `resultCode` (_string_) A code that indicates the specific type of error. * `message` (_string_) A message that describes the error.