Data Extension Imports

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.

  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"
  }