--- schema_version: "1" id: 3a01d6e5f4e78352f4334f2b140af015105a9ac6fb552fd173d2d831e5f9f2dd title: File Transfer Locations collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc-file_transfer_locations.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-file_transfer_locations source_site: developer.salesforce.com content_type: documentation content_hash: 588af66b4828c7380ef5f1a5cd34769c8df8e0545b41f7c5142939699e105fb8 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- File Transfer Locations # File Transfer Locations ## Overview A file location is an FTP site or other file storage location used to transfer files to or from your Marketing Cloud Engagement account. It's useful to create, rotate, manage and delete access keys, such as Amazon S3 credentials and external SFTP usernames and passwords. A file location configuration contains keys, passwords, and URLs. It's used with Automation Studio activities such as: * Imports * Data extracts * File transfer activities ### Base URI `https://{tsd}.rest.marketingcloudapis.com/` In the base URI example here, the abbreviation `{tsd}` is a placeholder to be replaced by the "tenant-specific domain". ### Supported Use Cases | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create a file location. | [POST](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Create%2Ba%2Bfile%2Btransfer%2Blocation) | data/v1/filetransferlocation | | Get all file locations. | [GET](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Get%2Ball%2Bfile%2Btransfer%2Blocations) | data/v1/filetransferlocations | | Get a specific file location. | [GET](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Get%2Ba%2Bfile%2Btransfer%2Blocation) | data/v1/filtransferlocation/{customerKey} | | Update a specific file location. | [PATCH](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Update%2Ba%2Bfile%2Btransfer%2Blocation) | data/v1/filtransferlocation/{customerKey} | | Deactivate a specific file location. | [DELETE](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Delete%2Ba%2Bfile%2Btransfer%2Blocation) | data/v1/filtransferlocation/{customerKey} | | Validate a file location. | [POST](/docs/marketing/marketing-cloud/references/mc-file_transfer_locations?meta=Validate%2Ba%2Bfile%2Btransfer%2Blocation) | data/v1/filtransferlocation/validate | **Version:** 1.0 ## Operations ### GET Get a file transfer location identified by customerKey. `GET /data/v1/filetransferlocation/{customerkey}` Operation ID: `Get a file transfer location`. This method returns a single file location for the given customer key. ### Required Scopes Installed Packages > Data > File Locations > Read `Scope: 'file_locations_read';` #### Parameters * `customerkey` (path, string, required) The customerkey of the FileTransferLocation to retrieve. Example: `AWS_Marketing_Bucket`. #### Responses * **200** OK Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Example Response_ ``` { "fileTransferLocation": { "customerKey": "AWS_Marketing_Bucket", "name": "AWS Marketing Bucket", "description": "Marketing files", "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "accessKeyId": "ASLKJMO45MTESTBYR3Q", "roleArn": "arn:aws:iam::123456789:role/Marketing_Role", "regionName": "useast1", "relativePath": "winter/registrations", "bucketName": "marketing", "authType": "AccessKeyWithIamRole" } }, "requestId": "f6204345-9600-4464-8fc0-96c701234e11", "resultMessages": [] } ``` ### DELETE Deactivate a file transfer location identified by customerKey. `DELETE /data/v1/filetransferlocation/{customerkey}` Operation ID: `Delete a file transfer location`. This method deactivates a file location based on a given customer key. ### Required Scopes Installed Packages > Data > File Locations > Write `Scope: 'file_locations_write';` #### Parameters * `customerkey` (path, string, required) The customerkey of the FileTransferLocation to delete. Example: `AWS_Marketing_Bucket`. #### Responses * **200** OK Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Example Response_ ``` { "requestId": "6ee6372c-cfd0-4a36-a17d-a5d1348221b1", "resultMessages": [] } ``` ### PATCH Update a file transfer location identified by customerKey. `PATCH /data/v1/filetransferlocation/{customerkey}` Operation ID: `Update a file transfer location`. This method updates a file location based on a given customer key. ### Required Scopes Installed Packages > Data > File Locations > Write `Scope: 'file_locations_write';` #### Parameters * `customerkey` (path, string, required) The customerkey of the FileTransferLocation to update. Example: `AWS_Marketing_Bucket`. #### Request body (required) Update an existing File Transfer Location. Media type: `application/json`. Schema: `fileTransferLocationRequestBody`. _Example: Update an AWS S3 file location with Access Key with IAM Role authorization_ ``` { "fileTransferLocation": { "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "authType": "AccessKeyWithIAMRole", "accessKeyId": "AKHDYEMO45MTESTBYR3Q", "SecretAccessKey": "TmlGlsDKA3GO05+AxeUdtmo70DJNSDPXJElZkzU1", } } } ``` #### Responses * **200** OK Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Example Response_ ``` { "fileTransferLocation": { "customerKey": "AWS_Marketing_Bucket", "name": "AWS Marketing Bucket", "description": "Marketing files", "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "accessKeyId": "AKHDYEMO45MTESTBYR3Q", "roleArn": "arn:aws:iam::123456789:role/Marketing_Role", "regionName": "useast1", "relativePath": "winter/registrations", "bucketName": "marketing", "authType": "AccessKeyWithIamRole" } }, "requestId": "34f3dc68-7c0f-4ffa-8cac-6e27e0123444", "resultMessages": [] } ``` ### GET Get all file transfer locations for the current MID `GET /data/v1/filetransferlocations` Operation ID: `Get all file transfer locations`. Tags: Get file transfer location collection. This method returns one or more file locations that are owned by, or reside under your member identification code (MID). A file location is also known as a `fileTransferLocation`. ### Required Scopes Installed Packages > Data > File Locations > Read `Scope: 'file_locations_read';` #### Parameters * `$page` (query, integer) This parameter selects the page returned from paginated results. It's usually used with the $pagesize parameter, described next. * `$pagesize` (query, integer) This parameter is the count of results to return per page. It's typically provided with $page. * `$locationType` (query, string) This parameter filters locations by their type. Allowed values: `ExternalSftp`, `AmazonSimpleStorage`, `AzureBlobStorage`, `GcpBlobStorage`. #### Responses * **200** OK Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Example Response_ ``` { "page": 1, "pageSize": 50, "count": 2, "items": [ { "customerKey": "AWS_Marketing_Bucket", "name": "AWS Marketing Bucket", "description": "Marketing files", "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "accessKeyId": "ASLKJMO45MTESTBYR3Q", "roleArn": "arn:aws:iam::123456789:role/Marketing_Role", "regionName": "useast1", "relativePath": "winter/registrations", "bucketName": "marketing", "authType": "AccessKeyWithIamRole" } }, { "customerKey": "External_SFTP_Location", "name": "Corporate SFTP", "description": "Corporate SFTP Location for marketing files", "locationType": "ExternalSftp", "sFtpFileTransferLocation": { "portNumber": 22, "userName": "myuser", "url": "sftp://externalsftp.com", "authType": "Password" } } ], "requestId": "181d4981-2a1b-4031-b1be-dcea1234b043", "resultMessages": [] } ``` ### POST Create a new File Transfer Location in your account. `POST /data/v1/filetransferlocation` Operation ID: `Create a file transfer location`. This method creates a new file location. For each of the types, parameters differ slightly, with differences shown below. ### Required Scopes Installed Packages > Data > File Locations > Write `Scope: 'file_locations_write';` #### Request body (required) Create a new File Transfer Location to your account. Media type: `application/json`. Schema: `fileTransferLocationRequestBody`. _Example: Create a new AWS S3 file location with Access Key with IAM Role authorization_ ``` { "fileTransferLocation": { "name": "AWS Marketing Bucket", "customerKey": "AWS_Marketing_Bucket", "description": "Marketing files", "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "authType": "AccessKeyWithIAMRole", "accessKeyId": "ASLKJMO45MTESTBYR3Q", "SecretAccessKey": "TmlGlTEST2GO05+AxeUdtmoTEST1DPXJElZkzU1", "RoleARN": "arn:aws:iam::123456789:role/Marketing_Role", "regionName": "useast1", "bucketName": "marketing", "relativePath": "winter/registrations" } } } ``` _Example: Create a new External SFTP S3 file location with username/password authentication_ ``` { "FileTransferLocation": { "name": "Corporate SFTP", "customerKey": "External_SFTP_Location", "description": "Corporate SFTP Location for marketing files", "locationType": "ExternalSftp", "sFtpFileTransferLocation": { "authType": "Password", "userName": "myuser", "password": "Password123", "url": "sftp://externalsftp.com" } } } ``` _Example: Create a new Azure file location with AAD authentication_ ``` { "fileTransferLocation": { "customerKey": "AzureBlobStorageAAD1", "name": "myTestLocation1", "description": "MyTestLocation1", "locationType": "AzureBlobStorage", "azureFileTransferLocation": { "accessKeyId": "accessKeyId1", "SecretAccessKey":"SecretAccessKey1", "relativePath": "relativePath1", "bucketName": "bucket1", "storageAccountName":"blobcont", "tenantId":"tenantId", "authType": "AccessKey" } } } ``` _Example: Create a new GCP Storage file location with credentials_ ``` { "fileTransferLocation":{ "customerKey":"GCPTestAPIDev", "name":"GCPTestAPIDev", "description":"GCPTestAPIDev", "locationType":"GcpBlobStorage", "gcpFileTransferLocation":{ "bucketName":"my-gcp-bucket", "authType":"CredentialFile", "credentials":{ "type":"service_account", "project_id":"my-project-id", "private_key_id":"REDACTED_GCP_PRIVATE_KEY_ID", "private_key":"-----BEGIN PRIVATE KEY-----\n --private key here -- \n-----END PRIVATE KEY-----\n", "client_email":"myuserdev@example.iam.gserviceaccount.com", "client_id":"113787057901699177331", "auth_uri":"https://accounts.google.com/o/oauth2/auth", "token_uri":"https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/my-gcp-bucket%40example.iam.gserviceaccount.com" } } } } ``` #### Responses * **200** File Transfer Location created. Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Create a new AWS S3 file location with Access Key with IAM Role authorization_ ``` { "fileTransferLocation": { "customerKey": "AWS_Marketing_Bucket", "name": "AWS Marketing Bucket", "description": "Marketing files", "locationType": "AmazonSimpleStorage", "awsFileTransferLocation": { "accessKeyId": "ASLKJMO45MTESTBYR3Q", "roleArn": "arn:aws:iam::123456789:role/Marketing_Role", "regionName": "useast1", "relativePath": "winter/registrations", "bucketName": "marketing", "authType": "AccessKeyWithIamRole" } }, "requestId": "47f76ce6-0fe8-422f-8568-fba01234bdb9", "resultMessages": [] } ``` _Example: Create a new External SFTP S3 file location with username/password authentication_ ``` { "fileTransferLocation": { "customerKey": "External_SFTP_Location", "name": "Corporate SFTP", "description": "Corporate SFTP Location for marketing files", "locationType": "ExternalSftp", "sFtpFileTransferLocation": { "portNumber": 22, "userName": "myuser", "url": "sftp://externalsftp.com", "authType": "Password" } }, "requestId": "42bdd95b-0668-42cf-a9c6-112345a5836e", "resultMessages": [] } ``` ### POST Validate a file transfer location schema passed in request body. `POST /data/v1/filetransferlocation/validate` Operation ID: `Validate a file transfer location`. This method validates a file location. For each of the types, parameters differ slightly, with differences shown below. ### Required Scopes Installed Packages > Data > File Locations > Write `Scope: 'file_locations_write';` #### Request body (required) Validate a new File Transfer Location. Media type: `application/json`. Schema: `fileTransferLocationRequestBody`. _Example: Validate a new Azure file location with SAS authentication_ ``` { "fileTransferLocation": { "customerKey": "AzureBlobStorageSAS", "name": "MyTestLocation", "description": "Azure Workign SAS String", "locationType": "AzureBlobStorage", "azureFileTransferLocation": { "relativePath": "relativePath", "bucketName": "blbocont", "storageAccountName":"blobtest", "authType": "SharedAccessSignature", "sasQueryString": "sp=racwdli&st=2022-04-13T20:46:36Z&se=2022-06-03T04:46:36Z&spr=https&sv=2020-08-04&sr=c&sig=egUGxZe%2Bp3Nab1NrRjE0WAL7bJpD7r%2Fazumx%2BaKAlU4%3D" } } } ``` #### Responses * **200** File Transfer Location validation complete. Media type: `application/json`. Schema: `any`. Type: `any`. _Example: Invalid bucket response_ ``` { "valid":false, "requestId":"ce6c58f3-9dc0-4cc8-a2d9-3cfa041d84f6", "resultMessages":[ { "resultType":"Validation", "resultClass":"Error", "resultCode":"Error", "message":"The specified bucket does not exist." } ] } ``` _Example: Valid FTL response_ ``` { "valid":true, "requestId":"ce6c58f3-9dc0-4cc8-a2d9-3cfa041d84f6", "resultMessages":[] } ``` ## Schemas ### fileTransferLocationRequestBody Request object for creating or updating a File Transfer Location. * `fileTransferLocation` (_awsFileTransferLocationRequest | sftpFileTransferLocationRequest | azureFileTransferLocationRequest | gcpFileTransferLocationRequest_, required) One of: `awsFileTransferLocationRequest`, `sftpFileTransferLocationRequest`, `azureFileTransferLocationRequest`, `gcpFileTransferLocationRequest`. ### awsFileTransferLocationRequest `fileTransferLocation` object for creating or updating an AWS File Transfer Location. * `name` (_string_, required) A name for your file location that identifies the location in Marketing Cloud Engagement. Example: `AWS Marketing Bucket`. * `customerKey` (_string_) The key used when using the API. Example: `AWS_Marketing_Bucket`. * `description` (_string_) A description of the file location. Example: `Marketing files`. * `locationType` (_string_, required) The type of File Transfer Location. Allowed values: `ExternalSftp`, `AmazonSimpleStorage`, `AzureBlobStorage`, `GcpBlobStorage`. Example: `AmazonSimpleStorage`. * `awsFileTransferLocation` (_awsFileTransferLocation_, required) ### sftpFileTransferLocationRequest `fileTransferLocation` object for creating or updating an SFTP File Transfer Location. * `name` (_string_, required) A name for your file location that identifies the location in Marketing Cloud Engagement. Example: `Corporate SFTP`. * `customerKey` (_string_) The key used when using the API. Example: `External_SFTP_Location`. * `description` (_string_) A description of the file location. Example: `Corporate SFTP Location for marketing files`. * `locationType` (_string_, required) The type of File Transfer Location. Allowed values: `ExternalSftp`, `AmazonSimpleStorage`, `AzureBlobStorage`, `GcpBlobStorage`. Example: `ExternalSftp`. * `sFtpFileTransferLocation` (_sFtpFileTransferLocation_, required) ### azureFileTransferLocationRequest `fileTransferLocation` object for creating or updating an Azure File Transfer Location. * `name` (_string_, required) A name for your file location that identifies the location in Marketing Cloud Engagement. Example: `AzureFileLocation`. * `customerKey` (_string_) The key used when using the API. Example: `AzureBlobStorageAAD1`. * `description` (_string_) A description of the file location. Example: `Azure File Location for marketing files`. * `locationType` (_string_, required) The type of File Transfer Location. Allowed values: `ExternalSftp`, `AmazonSimpleStorage`, `AzureBlobStorage`, `GcpBlobStorage`. Example: `AzureBlobStorage`. * `azureFileTransferLocation` (_gcpFileTransferLocation_, required) ### gcpFileTransferLocationRequest `fileTransferLocation` object for creating or updating an GCP File Transfer Location. * `name` (_string_, required) A name for your file location that identifies the location in Marketing Cloud Engagement. Example: `GCPFileLocation Marketing`. * `customerKey` (_string_) The key used when using the API. Example: `GCPFileLocation`. * `description` (_string_) A description of the file location. Example: `GCP File Location for marketing files`. * `locationType` (_string_, required) The type of File Transfer Location. Allowed values: `ExternalSftp`, `AmazonSimpleStorage`, `AzureBlobStorage`, `GcpBlobStorage`. Example: `GcpBlobStorage`. * `gcpFileTransferLocation` (_gcpFileTransferLocation_, required) ### awsFileTransferLocation `awsFileTransferLocation` object for specifying properties unique to AWS File Transfer Locations. * `authType` (_string_, required) The authorization method for the system to access the location. Allowed values: `AccessKey`, `AccessKeyWithIAMRole`. Example: `AccessKeyWithIAMRole`. * `accessKeyId` (_string_, required) The AWS Access Key ID for authorization. Example: `ASLKJMO45MTESTBYR3Q`. * `secretAccessKey` (_string_, required) The AWS Secret Access Key for authorization. Example: `TmlGlTEST2GO05+AxeUdtmoTEST1DPXJElZkzU1`. * `roleArn` (_string_) For AWS IAM Role authorization, use the Role ARN found in AWS. Required if `authType=AccessKeyWithIAMRole`. Example: `arn:aws:iam::1234567890/Role_Name`. * `regionName` (_string_, required) The region location of the bucket. Supported values are listed below. Allowed values: `useast1`, `uswest1`, `uswest2`, `euwest1`, `eucentral1`, `apnortheast1`, `apsoutheast1`, `apsoutheast2`, `saeast1`, `cnnorth1`, `useast2`, `eunorth1`, `euwest2`, `euwest3`, `eusouth1`, `apeast1`, `apnortheast2`, `apnortheast3`, `apsouth1`, `cnnorthwest1`, `cacentral1`, `mesouth1`, `afsouth1`. Example: `useast1`. * `bucketName` (_string_, required) The name of your bucket in AWS. Example: `marketing`. * `realtivepath` (_string_) The relative location inside the bucket. Don't use a leading or trailing "/" in your path. Example: `winter/registrations`. ### sFtpFileTransferLocation `sFtpFileTransferLocation` object for specifying properties unique to SFTP File Transfer Locations. * `authType` (_string_, required) Choose the authorization method for the system to access the location. Allowed values: `password`, `authKey`. Example: `Password`. * `url` (_string_, required) URL to the external SFTP location. Example: `sftp://externalsftp.com`. * `username` (_string_, required) Username to the external SFTP location. Example: `myuser`. * `password` (_string_) Password to the external SFTP location. Required if `authType=password`. Example: `Password123`. * `keyManagementPublicKey` (_string_) Public key for authenticating to the SFTP location. Required if `authType=authkey`. Example: `ASLKJMO45MTESTBYR3Q`. ### gcpFileTransferLocation `gcpFileTransferLocation` object for specifying properties unique to GCP File Transfer Locations. * `authType` (_string_, required) Specify the authorization method for the system to access the location. Allowed values: `CredentialFile`. Example: `CredentialFile`. * `bucketName` (_string_, required) The name of your bucket in GCP. Example: `myMarketingBucket`. * `credentials` (_object_, required) Credential information for authenticating to your GCP account. * `type` (_string_, required) The GCP account type. Example: `service_account`. * `project_id` (_string_, required) The GCP project id. Example: `marketing-winter`. * `private_key_id` (_string_, required) The GCP private key id. Example: `REDACTED_GCP_PRIVATE_KEY_ID`. * `private_key` (_string_, required) The GCP private key. Example: `-----BEGIN PRIVATE KEY----- -- private key here -- -----END PRIVATE KEY-----` . * `client_email` (_string_, required) The GCP account's associated email address. Example: `myuser@example.com`. * `client_id` (_string_, required) The GCP client id. Example: `113787057901699177331`. * `auth_uri` (_string_, required) The GCP authentication URI. Example: `https://accounts.google.com/o/oauth2/auth`. * `token_uri` (_string_, required) The GCP token URI. Example: `https://oauth2.googleapis.com/token`. * `auth_provider_x509_cert_url` (_string_, required) The GCP certificate URI. Example: `https://www.googleapis.com/oauth2/v1/certs`. * `client_x509_cert_url` (_string_, required) The GCP client specific certificate URL. Example: `https://www.googleapis.com/robot/v1/metadata/x509/myMarketingBucket%40myMarketingAccount.iam.gserviceaccount.com`. ### azureFileTransferLocation `azureFileTransferLocation` object for specifying properties unique to Azure File Transfer Locations. * `authType` (_string_, required) Choose the authorization method for the system to access the location. Allowed values: `SharedAccessSignature`, `AccessKey`. Example: `Password`. * `bucketName` (_string_, required) The name of your bucket in Azure. Example: `marketing`. * `realtivepath` (_string_) The relative location inside the bucket. Don't use a leading or trailing "/" in your path. Example: `winter/registrations`. * `storageAccountName` (_string_, required) Account user name in Azure. Example: `myuser`. * `sasQueryString` (_string_) Shared access signature query string. Required if `authType=SharedAccessSignature`. Example: `sp=racwdli&st=2022-04-13T20:46:36Z&se=2022-06-03T04:46:36Z&spr=https&sv=2020-08-04&sr=c&sig=egUGxZe%2Bp3Nab1NrRjE0WAL7bJpD7r%2Fazumx%2BaKAlU4%3D`. * `tenantId` (_string_) Tenant Id in Azure. Required if `authType=AccessKey` Example: `tenantId`. * `accessKeyId` (_string_) Access Key ID for authenticating to the Azure location. Required if `authType=AccessKey`. Example: `accessKeyId1`. * `SecretAccessKey` (_string_) Secret key for authenticating to the Azure location. Required if `authType=AccessKey`. Example: `SecretAccessKey1`.