---
schema_version: "1"
id: 10098a20c4f47d9d7156f965ced023be835c9c0f92a0acae1812afb08790bb65
title: Automation Studio
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc_rest_automation_studio_automations.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations
source_site: developer.salesforce.com
content_type: documentation
content_hash: 3773336aab78474c8ee0703b8e15a7bca0dd8822f9de147fd54a8b48b15df3df
products:
- Marketing Cloud Engagement APIs and Programmatic Languages
- Marketing Cloud
---
Automation Studio
# Automation Studio
Manage and execute multi-step marketing and data management activities on an immediate, triggered, or scheduled basis using automations.
This table lists the use cases that the API supports.
| Supported Use Case | HTTP Verb | URI |
| --- | --- | --- |
| [Get automations](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getAutomations) | GET | automation/v1/automations |
| [Create an automation](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=createAutomation) | POST | automation/v1/automations |
| [Get an automation](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getAutomation) | GET | automation/v1/automations/{id} |
| [Execute automation activities](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=executeAutomationActivities) | POST | automation/v1/automations/{id}/actions/runallonce |
| [Update an automation file trigger](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=updateAutomationFileTrigger) | PATCH | automation/v1/automations/filetrigger/{id} |
| [Update an automation file trigger by key](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=updateAutomationFileTriggerByKey) | PATCH | automation/v1/automations/filetrigger/key:{key} |
| [Execute automation activities by key](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=executeAutomationActivitiesByKey) | POST | automation/v1/automations/key:{key}/actions/runallonce |
| [Execute triggered automation](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=executeTriggeredAutomation) | POST | automation/v1/automations/trigger |
| [Update automation trigger](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=updateAutomationTrigger) | PATCH | automation/v1/automations/trigger/{id} |
| [Get trigger status](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getTriggerStatus) | GET | automation/v1/automations/trigger/status/{requestId} |
| [Get file transfer activities](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getFileTransferActivities) | GET | automation/v1/fileTransfers |
| [Create file transfer activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=createFileTransferActivity) | POST | automation/v1/fileTransfers |
| [Delete file transfer activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=deleteFileTransferActivity) | DELETE | automation/v1/fileTransfers/{fileTransferActivityId} |
| [Get file transfer activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getFileTransferActivity) | GET | automation/v1/fileTransfers/{fileTransferActivityId} |
| [Update file transfer activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=updateFileTransferActivity) | PATCH | automation/v1/fileTransfers/{fileTransferActivityId} |
| [Start file transfer activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=startFileTransferActivity) | POST | automation/v1/fileTransfers/{fileTransferActivityId}/start |
| [Get automation folders](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getAutomationFolders) | GET | automation/v1/folders |
| [Get FTP locations](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getFtpLocations) | GET | automation/v1/ftpLocations |
| [Get automation script activities](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=getAutomationScriptActivities) | GET | automation/v1/scripts |
| [Execute script activity](/docs/marketing/marketing-cloud/references/mc_rest_automation_studio_automations?meta=executeScriptActivity) | POST | automation/v1/scripts/{ssjsId}/start |
Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant:
**Version:** 1.0
## 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
### GET Retrieve a list of all automations in the account.
`GET /automation/v1/automations`
Operation ID: `getAutomations`.
### Required Scopes
To retrieve the automations in your account, your API user must have this permission:
* Automation | Automations | Read (`automations_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls.
Default: `1`.
* `$pagesize` (query, integer) The number of records to return on each page of results.
Default: `25`.
* `$filter` (query, string) A string that describes the filter to apply to the response. The filter must be URL encoded. Use single quotes for field values. Filters can include the `eq` and `neq` operators.
* `$orderBy` (query, string) The field and sort method to use to sort the results, such as `$orderBy=memberID ASC` to sort the results in ascending order by the value of the memberID field.
* `view` (query, string) Defines the type of extra data to return. The only accepted value is `targetdes`. If you specify this parameter, the response includes automations that have target data extensions.
#### Responses
* **200** Indicates that the request to retrieve all automations was successful.
Media type: `application/json`. Schema: `getAllAutomationsResponseBody`.
_Example_
```
{
"page": 1,
"pageSize": 25,
"count": 3,
"items": [
{
"id": "471671be-09b1-4bed-a661-3f0c8561646f",
"name": "Scheduled Automation",
"description": "",
"key": "Test123",
"typeId": 1,
"type": "scheduled",
"statusId": 3,
"status": "Running",
"categoryId": 1157180,
"lastRunTime": "2025-06-19T10:37:30.323",
"lastRunInstanceId": "8ec9be34-ef49-42b4-95d4-daabc893592b",
"schedule": {
"scheduleStatus": "none"
}
},
{
"id": "3ec3bec9-2eb5-4023-b49e-1ff51817ac01",
"name": "File Drop Automation",
"description": "",
"key": "77158f0c-bdd1-eaf4-62f6-5281d63d608f",
"typeId": 2,
"type": "triggered",
"statusId": 8,
"status": "InactiveTrigger",
"categoryId": 1157180,
"fileTrigger": {
"queueFiles": false,
"isPublished": false,
"fileNamePatternTypeId": 1,
"fileNamingPattern": "footer",
"folderLocationText": "triggered_automations\\",
"triggerActive": false
}
},
{
"id": "8eabb77c-1f7f-41e5-9f64-120009babcfe",
"name": "Triggered Automation",
"description": "",
"key": "f24d848b-b77b-4b63-bed2-a573523166fc",
"typeId": 2,
"type": "triggered",
"statusId": 8,
"status": "InactiveTrigger",
"categoryId": 1157180,
"automationTrigger": {
"queueFiles": true,
"filenamePattern": "example.csv",
"filenamePatternTypeId": 4,
"fileTransferLocationId": "e039f099-5e14-454e-a369-689e309f7699",
"sampleFileName": "example.csv",
"status": 1
}
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### POST Create an automation using existing Automation Studio activities.
`POST /automation/v1/automations`
Operation ID: `createAutomation`.
### Required Scopes
To create an automation, your API user must have this permission:
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
#### Request body
Media type: `application/json`. Schema: `createAutomationRequestBody`.
_Example: Create Scheduled Automation_
```
{
"name": "Example Scheduled Automation",
"description": "Example create of a scheduled automation",
"key": "example-scheduled-automation",
"steps": [
{
"annotation": "",
"stepNumber": 0,
"activities": [
{
"name": "1 Minute Wait",
"objectTypeId": 467,
"displayOrder": 0,
"activityObjectId": "00000000-0000-0000-0000-000000000000",
"serializedObject": "{\"duration\":1,\"durationUnits\":\"Minutes\"}"
}
]
}
],
"startSource": {
"typeId": 1,
"schedule": {
"icalRecur": "FREQ=DAILY;INTERVAL=1;UNTIL=20241011",
"startDate": "2024-08-11T06:00:00-04:00",
"timezoneId": 1
}
}
}
```
_Example: Create File Drop Automation_
```
{
"name": "Example File Drop Automation",
"description": "Example create for a file drop triggered automation",
"key": "example-file-drop-automation",
"steps": [
{
"annotation": "",
"stepNumber": 0,
"activities": [
{
"name": "1 Minute Wait",
"objectTypeId": 467,
"displayOrder": 0,
"activityObjectId": "00000000-0000-0000-0000-000000000000",
"serializedObject": "{\"duration\":1,\"durationUnits\":\"Minutes\"}"
}
]
}
],
"startSource": {
"typeId": 2,
"fileDrop": {
"filenamePattern": "example-pattern",
"filenamePatternTypeId": 2,
"folderLocation": "triggered_automations",
"queueFiles": true
}
}
}
```
_Example: Create AutomationTriggered Automation_
```
{
"name": "Example AutomationTriggered Automation",
"description": "Example create for an automationTriggered automation",
"key": "example-automation-triggered-automation",
"steps": [
{
"annotation": "",
"stepNumber": 0,
"activities": [
{
"name": "1 Minute Wait",
"objectTypeId": 467,
"displayOrder": 0,
"activityObjectId": "00000000-0000-0000-0000-000000000000",
"serializedObject": "{\"duration\":1,\"durationUnits\":\"Minutes\"}"
}
]
}
],
"startSource": {
"typeId": 5,
"automationTrigger": {
"queueFiles": true,
"filenamePattern": "example.csv",
"filenamePatternType": 4,
"fileTransferLocationId": "00000000-0000-0000-0000-000000000000",
"sampleFileName": "example.csv"
}
}
}
```
#### Responses
* **200** Indicates that the request to create an automation was successful.
Media type: `application/json`. Schema: `createAutomationResponseBody`.
_Example_
```
{
"id": "00000000-0000-0000-0000-000000000000",
"legacyId": "WV9HUWxHOKWSa2lhXzBrXzRaOVFkUToyNTow",
"name": "Example Scheduled Automation",
"description": "Example create for a scheduled automation",
"key": "example-scheduled-automation",
"categoryId": 3915,
"statusId": 4,
"lastSavedByName": "test-user",
"createdDate": "2024-11-08T11:50:02.693",
"createdByName": "test-user",
"updateInProgress": false,
"steps": [
{
"annotation": "",
"stepNumber": 0,
"activities": [
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "1 Minute Wait",
"description": "",
"activityObjectId": "00000000-0000-0000-0000-000000000000",
"objectTypeId": 467,
"displayOrder": 0,
"serializedObject": "{\"duration\":1,\"durationUnits\":\"Minutes\"}"
}
]
}
],
"startSource": {
"typeId": 1,
"schedule": {
"scheduleTypeId": 3,
"startDate": "2024-08-11T06:00:00-04:00",
"endDate": "2024-10-11T02:00:00-04:00",
"rangeTypeId": 1,
"occurrences": 61,
"icalRecur": "FREQ=DAILY;INTERVAL=1;UNTIL=20241011",
"timezoneId": 1,
"statusId": 0
}
}
}
```
* **400** Indicates that the request to create an automation failed. This error typically occurs when there’s an issue with the request body.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Name already exists: Name: Example_Automation_Name."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 specific automation by providing its ID.
`GET /automation/v1/automations/{id}`
Operation ID: `getAutomation`.
### Required Scopes
To retrieve an automation in your account, your API user must have this permission:
* Automation | Automations | Read (`automations_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `id` (path, string, required) The unique ID of the automation.
#### Responses
* **200** Indicates that the request to retrieve an automation was successful.
Media type: `application/json`. Schema: `getAutomationResponseBody`.
_Example_
```
{
"id": "62157360-59ec-4933-9058-f96b1f4e5b23",
"name": "Scheduled Automation",
"description": "",
"key": "c556e3ec-210f-2d4d-a7ad-bfc25ec674c0",
"typeId": 1,
"type": "scheduled",
"statusId": 2,
"status": "Ready",
"categoryId": 1157180,
"schedule": {
"scheduleStatus": "none"
},
"steps": [
{
"id": "b002f81e-dec9-4ff3-984c-b9964cbd9b23",
"name": "",
"step": 1,
"activities": [
{
"id": "1f5779e5-7ed1-4f16-b38a-137d21815a66",
"name": "Bounce",
"activityObjectId": "f9e9a893-3db0-e311-8f5c-ac162da3b19c",
"objectTypeId": 45,
"displayOrder": 1
}
]
},
{
"id": "9b9b0e94-1164-42a5-bd14-cfc2ef3a261e",
"name": "",
"step": 2,
"activities": [
{
"id": "01836759-0376-47f6-a0c8-10276c5ee85e",
"name": "AMPscript and PDF",
"activityObjectId": "f8aac5f0-494d-f011-ba70-d4f5ef3d4f4f",
"objectTypeId": 42,
"displayOrder": 1
},
{
"id": "bc31f0f4-6e03-489d-a36f-4b5ec3335905",
"name": "APINotOpened",
"activityObjectId": "7d8fbdf6-494d-f011-ba70-d4f5ef3d4f4f",
"objectTypeId": 45,
"displayOrder": 2
}
]
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Insufficient Privileges to complete this action.",
"errorcode": 20002,
"documentation": ""
}
```
* **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct email send definition key.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Not Found",
"errorcode": 0,
"documentation": "https://code.docs.exacttarget.com/rest/errors/404"
}
```
* **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"
}
```
### POST Run all activities in an automation one time by specifying its ID.
`POST /automation/v1/automations/{id}/actions/runallonce`
Operation ID: `executeAutomationActivities`.
### Required Scopes
To run the activities in an automation, your API user must have these permissions:
* Automation | Automations | Write (`automations_write`)
* Automation | Automations | Execute (`automations_execute`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `id` (path, string, required) The unique ID of the automation.
#### Responses
* **201** Indicates that the request to run all activities in an automation one time was successful.
Media type: `application/json`. Schema: `string`.
Text that indicates that the automation started successfully.
Type: `string`.
_Example_
```
Automation Started Successfully
```
* **400** Indicates that the request to run all activities in the automation failed. Typically, this error occurs when the automation is already running. This error is also returned if you try to run an automation that is triggered rather than scheduled.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "A run for this automation has already been started, you must wait for that run to complete before the automation can be started again."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Insufficient Privileges to complete this action.",
"errorcode": 20002,
"documentation": ""
}
```
* **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct email send definition key.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Not Found",
"errorcode": 0,
"documentation": "https://code.docs.exacttarget.com/rest/errors/404"
}
```
* **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"
}
```
### PATCH Activate or deactivate an automation file trigger by providing its ID.
`PATCH /automation/v1/automations/filetrigger/{id}`
Operation ID: `updateAutomationFileTrigger`.
### Required Scopes
To update the status of a trigger request, your API user must have this permission:
* Automation | Automations | Execute (`automations_execute`)
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `id` (path, string, required) The unique identifier of the file drop automation to update. This value is the same value that’s returned in the ID property from the `automation/v1/automations/` endpoint.
#### Request body
Media type: `application/json`. Schema: `object`.
* `isActive` (_boolean_, required) The status of the automation file trigger. If the value is `true`, the automation file trigger is activated. If the value is `false`, the automation file trigger is deactivated.
#### Responses
* **200** The request to update the automation file trigger status succeeded.
* **400** Indicates that the request to update the automation file trigger status failed. This error typically occurs when the folder is already in use. In this situation, deactivate any file drop automations that are listening for the same file pattern in the same folder. If any automations that use the same file trigger are running, wait for them to complete before deactivating the file trigger. If the Guid is invalid or the automation can’t be found, make sure that the `id` in the request is a valid GUID and corresponds to an existing file drop automation.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Folder triggered_automations location is in use."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### PATCH Activate or deactivate an automation file trigger by providing its key.
`PATCH /automation/v1/automations/filetrigger/key:{key}`
Operation ID: `updateAutomationFileTriggerByKey`.
### Required Scopes
To update the status of a trigger request, your API user must have this permission:
* Automation | Automations | Execute (`automations_execute`)
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `key` (path, string, required) The user-defined external key of the automation file trigger.
#### Request body
Media type: `application/json`. Schema: `object`.
* `isActive` (_boolean_, required) The status of the automation file trigger. If the value is `true`, the automation file trigger is activated. If the value is `false`, the automation file trigger is deactivated.
#### Responses
* **200** The request to update the automation file trigger status succeeded.
* **400** Indicates that the request to update the automation file trigger status failed. This error typically occurs when the folder is already in use. In this situation, deactivate any file drop automations that are listening for the same file pattern in the same folder. If any automations that use the same file trigger are running, wait for them to complete before deactivating the file trigger. If the Guid is invalid or the automation can’t be found, make sure that the `id` in the request is a valid GUID and corresponds to an existing file drop automation.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Folder triggered_automations location is in use."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### POST Run all activities in an automation one time by specifying its external key.
`POST /automation/v1/automations/key:{key}/actions/runallonce`
Operation ID: `executeAutomationActivitiesByKey`.
### Required Scopes
To run the activities in an automation, your API user must have these permissions:
* Automation | Automations | Write (`automations_write`)
* Automation | Automations | Execute (`automations_execute`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `key` (path, string, required) The user-defined external key of the automation.
#### Responses
* **201** Indicates that the request to run all activities in an automation one time was successful.
Media type: `application/json`. Schema: `string`.
Text that indicates that the automation started successfully.
Type: `string`.
_Example_
```
Automation Started Successfully
```
* **400** Indicates that the request to run all activities in the automation failed. Typically, this error occurs when the automation is already running. This error is also returned if you try to run an automation that is triggered rather than scheduled.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "A run for this automation has already been started, you must wait for that run to complete before the automation can be started again."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Insufficient Privileges to complete this action.",
"errorcode": 20002,
"documentation": ""
}
```
* **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct email send definition key.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Not Found",
"errorcode": 0,
"documentation": "https://code.docs.exacttarget.com/rest/errors/404"
}
```
* **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"
}
```
### POST Start an automation that uses a trigger start source.
`POST /automation/v1/automations/trigger`
Operation ID: `executeTriggeredAutomation`.
When you upload a file, the Trigger API request passes the file details for Automation Studio to evaluate. You can queue a maximum of 200 Trigger requests at a time in each member ID (MID).
### Required scopes
To trigger an automation, your API user must have this permission:
* Automation | Automations | Execute (`automations_execute`)
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
#### Request body
Media type: `application/json`. Schema: `triggerAutomationRequestBody`.
#### Responses
* **200** Indicates that the request to trigger an automation was successful.
Media type: `application/json`. Schema: `object`.
* `requestId` (_string_) A unique identifier for the request to trigger the automation. If errors prevent the automation from being triggered, the value is `00000000-0000-0000-0000-000000000000`.
* `errors` (_array of object_) An array of objects. Each object contains details about an error. If no errors occur, this property is omitted.
* `message` (_string_) A message that describes the error.
_Example: Successful Request_
```
{
"requestId": "b8439846-1837-4df4-b5a2-c9e3dec7d89f"
}
```
_Example: Request with Errors_
```
{
"requestId": "00000000-0000-0000-0000-000000000000",
"errors": [
{
"message": "The following field is not valid for the current operation: 'FileTransferLocationKey'"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Insufficient Privileges to complete this action.",
"errorcode": 20002,
"documentation": ""
}
```
* **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct email send definition key.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Not Found",
"errorcode": 0,
"documentation": "https://code.docs.exacttarget.com/rest/errors/404"
}
```
* **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"
}
```
### PATCH Activate or Deactivate an Automation Trigger.
`PATCH /automation/v1/automations/trigger/{id}`
Operation ID: `updateAutomationTrigger`.
### Required scopes
To update the status of a trigger request, your API user must have this permission:
* Automation | Automations | Execute (`automations_execute`)
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `id` (path, string, required) The unique ID of the automation.
#### Request body
Media type: `application/json`. Schema: `updateAutomationTriggerRequestBody`.
#### Responses
* **200** Indicates that the request to update an automation trigger was successful.
Media type: `application/json`. Schema: `string`.
Text that indicates that the automation trigger was updated successfully.
Type: `string`.
_Example_
```
OK
```
* **400** Indicates that the request to update an automation trigger failed. This error typically occurs when the automation trigger ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 Check the status for a specified Trigger API requestID.
`GET /automation/v1/automations/trigger/status/{requestId}`
Operation ID: `getTriggerStatus`.
> Note
>
> To see the automation details, make sure that the request’s file details meet the criteria for exactly one automation trigger configuration. See _Salesforce Help_: [Configure a Trigger Automation](https://help.salesforce.com/s/articleView?id=mktg.mc_as_define_a_file_trigger_automation.htm).
### Required scopes
To check the status of a trigger request, your API user must have this permission:
* Automation | Automations | Read (`automations_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `requestId` (path, string, required) The unique ID of the trigger request. The API returns this value in the `requestId` property of the response to the POST request to start the automation using the trigger start source.
#### Responses
* **200** Indicates that the request to check the status of a trigger request was successful.
Media type: `application/json`. Schema: `getTriggerStatusResponseBody`.
_Example_
```
{
"triggerdetails": {
"status": "AutomationTriggered",
"automationDetails": {
"automationName": "My Import Automation",
"automationExternalKey": "Import_Automation_API_Key"
}
},
"triggerRequestID": "e2dd2b55-431b-404e-b80b-6b1ad6bd527e",
"resultMessages": []
}
```
* **400** Indicates that the request to check the status of a trigger request failed. This error typically occurs when the trigger request ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 all file transfer activities in the account.
`GET /automation/v1/fileTransfers`
Operation ID: `getFileTransferActivities`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls.
Default: `1`.
* `$pagesize` (query, integer) The number of records to return on each page of results.
Default: `25`.
* `$filter` (query, string) A string that describes the filter to apply to the response. The filter must be URL encoded. Use single quotes for field values. Filters can include the `eq` and `neq` operators.
* `$orderBy` (query, string) The field and sort method to use to sort the results. The only supported properties for ordering are `name` and `customerkey`. You can sort results in ascending (`ASC`)or descending (`DESC`) order.
#### Responses
* **200** Indicates that the request to retrieve all file transfer activities was successful.
Media type: `application/json`. Schema: `getFileTransferActivitiesResponseBody`.
_Example_
```
{
"page": 1,
"pageSize": 25,
"count": 1,
"items": [
{
"id": "1aaca000-9c6d-40e0-95d9-2d7ca324970a",
"name": "Transfer a File",
"customerKey": "1AACA000-9C6D-40E0-95D9-2D7CA324970A",
"createdDate": "2025-10-06T12:51:39.947",
"modifiedDate": "2025-10-06T12:51:39.947"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### POST Create a file transfer activity.
`POST /automation/v1/fileTransfers`
Operation ID: `createFileTransferActivity`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
#### Request body
Media type: `application/json`. Schema: `createFileTransferActivityRequestBody`.
#### Responses
* **200** Indicates that the request to create a file transfer activity was successful.
Media type: `application/json`. Schema: `createFileTransferActivityResponseBody`.
_Example_
```
{
"id": "f18d0533-912a-4545-923d-4b80495b92e8",
"name": "Test Encryption",
"customerKey": "b7d1949c-cfaf-4d74-97f6-e2b2da521b56",
"fileSpec": "test-2.txt.pgp",
"isEncrypted": true,
"isCompressed": false,
"maxFileAge": 0,
"maxFileAgeScheduleOffset": 0,
"maxImportFrequency": 0,
"fileTransferLocationId": "1f91eb52-9a28-4469-8808-accdc4325ced",
"isUpload": false,
"isPgp": false,
"isFileSpecLocalized": false,
"createdDate": "2019-05-16T14:41:29.24",
"modifiedDate": "2021-04-26T20:54:18.71"
}
```
* **400** Indicates that the request to create a file transfer activity failed. This error typically occurs required properties are missing from the request body.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "The value specified for the following field is not valid: 'Name'."
},
{
"message": "The value specified for the following field is not valid: 'FileSpec'."
},
{
"message": "The value specified for the following field is not valid: 'FileTransferLocationId'."
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 specific file transfer activity by providing its ID.
`GET /automation/v1/fileTransfers/{fileTransferActivityId}`
Operation ID: `getFileTransferActivity`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `fileTransferActivityId` (path, string, required) The unique ID of the file transfer activity.
#### Responses
* **200** Indicates that the request to retrieve a file transfer activity was successful.
Media type: `application/json`. Schema: `createFileTransferActivityResponseBody`.
_Example: same as POST /automation/v1/fileTransfers 200 response._
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### DELETE Delete a specific file transfer activity by providing its ID.
`DELETE /automation/v1/fileTransfers/{fileTransferActivityId}`
Operation ID: `deleteFileTransferActivity`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `fileTransferActivityId` (path, string, required) The unique ID of the file transfer activity.
#### Responses
* **200** Indicates that the request to delete a file transfer activity was successful. The response body is empty.
Media type: `application/json`. Schema: `object`.
_Example_
```
{}
```
* **400** Indicates that the request to delete a file transfer activity failed. This error typically occurs when the file transfer activity ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### PATCH Update a file transfer activity by providing its ID.
`PATCH /automation/v1/fileTransfers/{fileTransferActivityId}`
Operation ID: `updateFileTransferActivity`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `fileTransferActivityId` (path, string, required) The unique ID of the file transfer activity.
#### Request body
Media type: `application/json`. Schema: `createFileTransferActivityRequestBody`.
#### Responses
* **200** Indicates that the request to create a file transfer activity was successful.
Media type: `application/json`. Schema: `createFileTransferActivityResponseBody`.
_Example: same as POST /automation/v1/fileTransfers 200 response._
* **400** Indicates that the request to delete a file transfer activity failed. This error typically occurs when the file transfer activity ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### POST Add a file transfer activity to the queue for processing.
`POST /automation/v1/fileTransfers/{fileTransferActivityId}/start`
Operation ID: `startFileTransferActivity`.
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `fileTransferActivityId` (path, string, required) The unique ID of the file transfer activity.
#### Responses
* **200** Indicates that the request to add a file transfer activity to the queue for processing was successful. The response body is empty.
Media type: `application/json`.
_Example_
```
{}
```
* **400** Indicates that the request to add a file transfer activity to the queue for processing failed. This error typically occurs when the file transfer activity ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 all folders in the account.
`GET /automation/v1/folders`
Operation ID: `getAutomationFolders`.
### Required Scopes
To retrieve automation folders, your API user must have this permission:
* Automation | Automations | Read (`automations_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `$filter` (query, string, required) A string that describes the filter to apply to the response. To retrieve all folders, use the filter `categorytype eq automations`.
Example: `categorytype eq automations`.
#### Responses
* **200** Indicates that the request to retrieve all folders was successful.
Media type: `application/json`. Schema: `getFoldersResponseBody`.
_Example_
```
{
"count": 2,
"page": 1,
"pageSize": 25,
"items": [
{
"categoryId": 1157180,
"categoryType": "automations",
"hasChildren": false,
"name": "Automation Folder",
"parentId": "0"
},
{
"categoryId": 1157180,
"categoryType": "automations",
"hasChildren": true,
"name": "Automation Folder 2",
"parentId": "1157180"
}
]
}
```
* **400** Indicates that the request to retrieve all folders failed. Typically, this error occurs when the filter parameter is invalid.
Media type: `application/json`. Schema: `object`.
* `errors` (_array of object_) An array of objects. Each object contains details about an error.
* `message` (_string_) The error message.
_Example_
```
{
"errors": [
{
"message": "The following URL parameter is required for this request: $filter"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 all FTP locations in the account.
`GET /automation/v1/ftpLocations`
Operation ID: `getFtpLocations`.
### Required Scopes
To retrieve FTP locations, your API user must have this permission:
* Automation | Automations | Read (`automations_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
#### Responses
* **200** Indicates that the request to retrieve all FTP locations was successful.
Media type: `application/json`. Schema: `getFtpLocationsResponseBody`.
_Example_
```
{
"page": 1,
"pageSize": 2,
"count": 2,
"items": [
{
"name": "NTO FTP Server",
"id": "57a04cae-f8dd-4aa7-b45a-21a23b58465e",
"locationTypeId": 2,
"locationUrl": "sftp://test.example.com"
},
{
"name": "ExactTarget Enhanced FTP",
"id": "89bcb5a0-352a-44ec-8f71-d24fa730e39d",
"locationTypeId": 0
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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 automation script activities.
`GET /automation/v1/scripts`
Operation ID: `getAutomationScriptActivities`.
### Required Scopes
To retrieve script activities, your API user must have this permission:
* Automation | Scripts | Read (`scripts_read`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `$filter` (query, string) A string that describes the filter to apply to the response. The filter must be URL encoded. Use single quotes for field values. Filters can include the `eq` and `neq` operators.
* `$orderBy` (query, string) The field and sort method to use to sort the results, such as `$orderBy=memberID ASC` to sort the results in ascending order by the value of the memberID field.
* `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls.
Default: `1`.
* `$pagesize` (query, integer) The number of records to return on each page of results.
Default: `25`.
#### Responses
* **200** Indicates that the request to retrieve all automation scripts was successful.
Media type: `application/json`. Schema: `getScriptsResponseBody`.
_Example_
```
{
"count": 2,
"page": 1,
"pageSize": 25,
"items": [
{
"ssjsActivityId": "d0f9a455-dd5d-49eb-8b97-2049a30a76e8",
"name": "%%view_email_url%%",
"key": "68f3d824-8507-4f6e-a2d4-f7ab3bb66502",
"description": "",
"script": "",
"categoryId": 4291460,
"createdDate": "2022-05-16T06:54:34.907",
"modifiedDate": "2023-01-23T13:20:34.803"
},
{
"ssjsActivityId": "341393ca-a8c1-4a9e-8dfd-a117c2fe7d0c",
"name": "0030e672-78b9-45ce-8708-eeabca3f5485",
"key": "0030e672-78b9-45ce-8708-eeabca3f5485",
"description": "0030e672-78b9-45ce-8708-eeabca3f5485",
"script": "",
"categoryId": 0,
"createdDate": "2023-08-11T02:15:21.213",
"modifiedDate": "2023-08-11T02:15:21.213"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "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"
}
```
### POST Run a script activity one time.
`POST /automation/v1/scripts/{ssjsId}/start`
Operation ID: `executeScriptActivity`.
### Required Scopes
To run a script activity, your API user must have this permission:
* Automation | Automations | Execute (`automations_execute`)
* Automation | Automations | Write (`automations_write`)
#### Parameters
* `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token.
_Example_
```
Bearer YOUR_ACCESS_TOKEN
```
* `ssjsId` (path, string, required) The unique ID of the script activity.
#### Responses
* **201** Indicates that the request to run a script activity was successful.
Media type: `application/json`. Schema: `string`.
Text that indicates that the script activity started successfully.
Type: `string`.
_Example_
```
OK
```
* **400** Indicates that the request to run a script activity failed. This error typically occurs when the script ID is invalid.
Media type: `application/json`. Schema: `errorsObject`.
_Example_
```
{
"errors": [
{
"message": "Identifying Guid is invalid and could not be parsed"
}
]
}
```
* **401** Indicates that the API wasn’t able to 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. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Insufficient Privileges to complete this action.",
"errorcode": 20002,
"documentation": ""
}
```
* **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct email send definition key.
Media type: `application/json`. Schema: `mceErrorResponseBody`.
_Example_
```
{
"message": "Not Found",
"errorcode": 0,
"documentation": "https://code.docs.exacttarget.com/rest/errors/404"
}
```
* **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
### getAllAutomationsResponseBody
* `count` (_integer_) The total number of records that match the filter criteria.
* `items` (_array of object_) An array of objects. Each object contains details about an automation.
* `automationTrigger` (_object_) Defines the automation trigger start source properties if applicable to the automation.
* `filenamePattern` (_string_) The file name format to match against files submitted to the API to start the automation.
* `filenamePatternTypeId` (_integer_) Defines how the `fileNamePattern` property is matched against a filename to determine whether to run the automation. Possible values are `0` (none), `1` (contains), `2` (beginsWith), `3` (endsWith), and `4` (equals).
Minimum: 0. Maximum: 4.
* `fileTransferLocationId` (_string_) The `fileTransferLocationId` of a file transfer location defined in this account. This location is used to download the file for processing.
* `queueFiles` (_boolean_) When true, dropped files queue if an automation instance is executing. When false, dropped files cause a skipped automation instance.
* `sampleFileName` (_string_) An example filename used to validate the automation trigger parameters and also ensure other definitions do not match the same file.
* `status` (_integer_) A numeric representation of the status of the automation trigger.
* `categoryId` (_integer_) The ID of the category that the automation belongs to.
* `description` (_string_) A description of the automation.
* `fileTrigger` (_object_) An object that defines the file drop start source properties. This object is only included in the response if the automation type is `fileTrigger`.
* `fileNamePatternTypeId` (_integer_) If a filename pattern is defined, this property indicates how to match the pattern against the file name. Possible values are `0` (none), `1` (contains), `2` (beginsWith), and `3` (endsWith).
Minimum: 0. Maximum: 3.
* `fileNamingPattern` (_string_) If a filename pattern is defined, this property contains the text to match in the file name.
* `folderLocationText` (_string_) The folder to monitor for uploaded files. The path must be relative to the account’s home folder in the Enhanced SFTP service.
* `isPublished` (_boolean_) Indicates whether the file drop is activated and monitoring for uploaded files. If the value is `true`, the file drop is activated and monitoring for uploaded files.
* `queueFiles` (_boolean_) Indicates whether to add files to a queue if a file is added to the file drop location while the automation is running. If the value is `true`, files are added to a queue. If the value is `false`, the files are skipped.
* `triggerActive` (_boolean_) Indicates whether the file drop automation is listening for uploaded files. This property matches the value of the `isPublished` property.
* `id` (_string_) The unique ID of the automation.
* `key` (_string_) A user-defined key for the automation.
* `lastRunTime` (_string_) The date and time when the automation last finished running.
* `lastRunInstanceId` (_string_) A unique identifier for the last finished run of the automation.
* `name` (_string_) The name of the automation.
* `schedule` (_object_) An object that defines the schedule of the automation.
* `scheduleStatus` (_string_) The status of the schedule.
Allowed values: `none`.
* `status` (_string_) The status of the automation.
Allowed values: `AwaitingTrigger`, `Building`, `BuildingError`, `Error`, `InactiveTrigger`, `Initialized`, `PausedExecution`, `PausedSchedule`, `Ready`, `Running`, `Scheduled`, `Stopped`.
* `statusId` (_integer_) A numeric representation of the status of the automation. The value of this property corresponds to the value of the `status` property.
Minimum: 0. Maximum: 10.
* `type` (_string_) The start source of the automation. This property corresponds to the value of the `typeId` property.
* `typeId` (_integer_) Numeric identifier to represent the type of automation start source. Possible values are `0` (unspecified), `1` (scheduled), `2` (triggered), `3` (chained), `4` (jbEvent), or `5` (automationTriggered).
Minimum: 0. Maximum: 5.
* `page` (_integer_) The current page number of results.
* `pageSize` (_integer_) The number of records on each page of results.
### 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.
### createAutomationRequestBody
* `categoryId` (_integer_) The ID of the category that the automation belongs to.
* `description` (_string_) A description of the automation.
* `key` (_string_) A user-defined key for the automation.
* `name` (_string_) The name of the automation.
* `steps` (_array of object_) The steps of the automation.
* `annotation` (_string_) A description of the step.
* `stepNumber` (_integer_) The number of the step in the automation. The first step in the automation has a step number of `0`.
* `activities` (_object_) An object that defines the activities that occur in the step.
* `name` (_string_) The name of the activity.
* `description` (_string_) A description of the activity.
* `activityObjectId` (_string_) The unique ID of the activity.
* `objectTypeId` (_integer_) The type of object that the activity belongs to.
* `displayOrder` (_integer_) The order in which the activity occurs in the step. The first activity in the step has a display order of `0`.
* `serializedObject` (_object_) The serialized object that defines the activity.
* `startSource` (_object_) The start source of the automation.
* `automationTrigger` (_object_) An object that defines the automation trigger start source properties. This object is required for triggered automations.
* `customerKey` (_string_) The customer-defined unique identifier for this automation trigger. If you don’t explicitly define a value, the API generates a GUID.
* `fileNamePattern` (_string_) The file name format to match against files submitted to the API to start the automation.
* `fileNamePatternType` (_integer_) Defines how the `fileNamePattern` property is matched against a filename to determine whether to run the automation. Possible values are `0` (none), `1` (contains), `2` (begins with), `3` (ends with), and `4` (equals).
Minimum: 0. Maximum: 4.
* `fileTransferLocationId` (_string_) The ID of the file transfer location for the file transfer activity. For information about creating a file transfer location, see _Salesforce Help_: [Set Up an External FTP File Location with Marketing Cloud Engagement](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_set_up_external_ftp_location.htm).
* `folderLocation` (_string_) The folder in the file transfer location to monitor for uploaded files.
* `programId` (_string_) The unique system-generated automation definition ID associated with the automation trigger.
* `queueFiles` (_boolean_) Indicates whether to add files to a queue if a file is added to the file drop location while the automation is running. If the value is `true`, files are added to a queue. If the value is `false`, the files are skipped.
* `sampleFileName` (_string_) An example filename used to validate the automation trigger parameters and also ensure other definitions don’t match the same file.
* `fileDrop` (_object_) An object that defines the file drop start source properties. This object is required for file drop automations.
* `fileNamePattern` (_string_) The file name format to match against files submitted to the API to start the automation.
* `fileNamePatternTypeId` (_integer_) Defines how the `fileNamePattern` property is matched against a filename to determine whether to run the automation. Possible values are `0` (none), `1` (contains), `2` (begins with), `3` (ends with), and `4` (equals).
Minimum: 0. Maximum: 4.
* `fileTransferLocationId` (_string_) The ID of the file transfer location for the file transfer activity. For information about creating a file transfer location, see _Salesforce Help_: [Set Up an External FTP File Location with Marketing Cloud Engagement](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_set_up_external_ftp_location.htm).
* `folderLocation` (_string_) The folder in the file transfer location to monitor for uploaded files.
* `isPublished` (_boolean_) Indicates whether the automation trigger is published.
* `queueFiles` (_boolean_) Indicates whether to add files to a queue if a file is added to the file drop location while the automation is running. If the value is `true`, files are added to a queue. If the value is `false`, the files are skipped.
* `schedule` (_object_) An object that defines the schedule of and recurrence rules for the automation. This object is required for scheduled automations.
* `endDate` (_string_) The end date of the schedule.
* `icalRecur` (_string_) The recurrence rules for the schedule in iCalendar format.
* `occurrences` (_integer_) If the the value of `rangeTypeId` is `1`, this value defines the number of intervals before the schedule ends.
* `rangeTypeId` (_integer_) Indicates whether the schedule ends after a specific date or after a number of intervals. If the value is `0`, the schedule ends after a specific date. If the value is `1`, the schedule ends after a specified number of intervals.
* `startDate` (_string_) The start date of the schedule.
* `scheduleTypeId` (_integer_) The recurrence type for the schedule. Possible values are `0` (every second), `1` (every minute), `2` (every hour), `3` (every day), `4` (every week), `5` (every month), `6` (every year).
* `timeZoneId` (_integer_, required) The ID of the time zone of the schedule. This value is required for scheduled automations. For a list of time zones, see [Available Time Zones](/docs/marketing/marketing-cloud/guide/timezone.html#available-time-zones).
Minimum: 1. Maximum: 92.
* `typeId` (_integer_, required) The type of start source for the automation. Possible values are `0` (unspecified), `1` (scheduled), `2` (triggered), `3` (chained), `4` (Journey Builder event), or `5` (automation triggered).
### createAutomationResponseBody
* `categoryId` (_integer_) The ID of the category that the automation belongs to.
* `createdByName` (_string_) The name of the user who created the automation.
* `createdDate` (_string_) The date and time when the automation was created.
* `description` (_string_) A description of the automation.
* `id` (_string_) The unique ID of the automation.
* `key` (_string_) A user-defined key for the automation.
* `legacyId` (_string_) The legacy ID of the automation.
* `lastSavedByName` (_string_) The name of the user who last saved the automation.
* `name` (_string_) The name of the automation.
* `startSource` (_object_) The start source of the automation.
* `automationTrigger` (_object_) An object that defines the automation trigger start source properties. This object is returned only when you create a triggered automation.
* `customerKey` (_string_) The customer-defined unique identifier for this automation trigger.
* `fileNamePattern` (_string_) The file name format to match against files submitted to the API to start the automation.
* `fileNamePatternType` (_integer_) Defines how the `fileNamePattern` property is matched against a filename to determine whether to run the automation. Possible values are `0` (none), `1` (contains), `2` (begins with), `3` (ends with), and `4` (equals).
Minimum: 0.
* `fileTransferLocationId` (_string_) The ID of the file transfer location for the file transfer activity.
* `folderLocation` (_string_) The folder in the file transfer location that’s being monitored for uploaded files.
* `queueFiles` (_boolean_) Indicates whether to add files to a queue if a file is added to the file drop location while the automation is running. If the value is `true`, files are added to a queue. If the value is `false`, the files are skipped.
* `sampleFileName` (_string_) An example filename used to validate the automation trigger parameters and also ensure other definitions don’t match the same file.
* `statusId` (_integer_) The ID of the status of the automation.
* `fileDrop` (_object_) An object that defines the file drop start source properties. This object is returned only when you create a file drop automation.
* `fileNamePattern` (_string_) The file name format to match against files submitted to the API to start the automation.
* `fileNamePatternTypeId` (_integer_) Defines how the `fileNamePattern` property is matched against a filename to determine whether to run the automation. Possible values are `0` (none), `1` (contains), `2` (begins with), `3` (ends with), and `4` (equals).
Minimum: 0. Maximum: 4.
* `folderLocation` (_string_) The folder in the file transfer location that’s being monitored for uploaded files.
* `queueFiles` (_boolean_) Indicates whether to add files to a queue if a file is added to the file drop location while the automation is running. If the value is `true`, files are added to a queue. If the value is `false`, the files are skipped.
* `statusId` (_integer_) The ID of the status of the automation.
* `schedule` (_object_) An object that defines the schedule of and recurrence rules for the automation. This object is returned only when you create a scheduled automation.
* `endDate` (_string_) The end date of the schedule.
* `icalRecur` (_string_) The recurrence rules for the schedule in iCalendar format.
* `occurrences` (_integer_) If the the value of `rangeTypeId` is `1`, this value defines the number of intervals before the schedule ends.
* `rangeTypeId` (_integer_) Indicates whether the schedule ends after a specific date or after a number of intervals. If the value is `0`, the schedule ends after a specific date. If the value is `1`, the schedule ends after a specified number of intervals.
* `scheduleTypeId` (_integer_) The recurrence type for the schedule. Possible values are `0` (every second), `1` (every minute), `2` (every hour), `3` (every day), `4` (every week), `5` (every month), `6` (every year).
* `startDate` (_string_) The start date of the schedule.
* `statusId` (_integer_) The ID of the status of the automation.
* `timeZoneId` (_integer_) The ID of the time zone of the schedule. This value is required for scheduled automations. For a list of time zones, see [Available Time Zones](/docs/marketing/marketing-cloud/guide/timezone.html#available-time-zones).
Minimum: 1. Maximum: 92.
* `typeId` (_integer_) The type of start source for the automation. Possible values are `0` (unspecified), `1` (scheduled), `2` (triggered), `3` (chained), `4` (Journey Builder event), or `5` (automation triggered).
* `statusId` (_integer_) The ID of the status of the automation.
* `steps` (_array of object_) An array of objects. Each object contains details about a step in the automation.
* `annotation` (_string_) The annotation of the step.
* `stepNumber` (_integer_) The number of the step in the automation. The first step in the automation has a step number of `0`.
* `activities` (_array of object_) An array of objects. Each object contains details about an activity in the step.
* `name` (_string_) The name of the activity.
* `description` (_string_) A description of the activity.
* `activityObjectId` (_string_) The unique ID of the activity.
* `objectTypeId` (_integer_) The type of object that the activity belongs to.
* `displayOrder` (_integer_) The order in which the activity occurs in the step. The first activity in the step has a display order of `0`.
* `serializedObject` (_object_) The serialized object that defines the activity.
* `updateInProgress` (_boolean_) Indicates whether the automation is being updated.
### errorsObject
* `errors` (_array of object_) An array of objects. Each object contains details about an error.
* `message` (_string_) The error message.
### getAutomationResponseBody
* `id` (_string_) The unique ID of the automation.
* `name` (_string_) The name of the automation.
* `description` (_string_) A description of the automation.
* `key` (_string_) A user-defined key for the automation.
* `typeId` (_integer_) Numeric identifier to represent the type of automation start source. Possible values are `0` (unspecified), `1` (scheduled), `2` (triggered), `3` (chained), `4` (jbEvent), or `5` (automationTriggered).
Minimum: 0. Maximum: 5.
* `type` (_string_) The start source of the automation. This property corresponds to the value of the `typeId` property.
* `statusId` (_integer_) A numeric representation of the status of the automation. The value of this property corresponds to the value of the `status` property.
Minimum: 0. Maximum: 10.
* `status` (_string_) The status of the automation.
Allowed values: `AwaitingTrigger`, `Building`, `BuildingError`, `Error`, `InactiveTrigger`, `Initialized`, `PausedExecution`, `PausedSchedule`, `Ready`.
* `categoryId` (_integer_) The ID of the category that the automation belongs to.
* `lastRunTime` (_string_) The date and time when the automation last finished running.
* `schedule` (_object_)
* `scheduleStatus` (_string_) The status of the schedule.
Allowed values: `none`.
* `steps` (_stepsArray_)
### triggerAutomationRequestBody
* `fileTransferLocationKey` (_string_) The file location API identifier.
* `filename` (_string_) The name of the file to use for the automation.
* `relativePath` (_string_)
The relative folder path from the top-level container, not including the bucket or container name.
> Note
>
> When you upload a file to a folder with a dynamic structure or naming convention, we recommend that you create a file location at the root bucket, container, or directory. Then, use the `relativepath` parameter to dynamically specify the path to the file.
* `deduplicationKey` (_string_) A unique alphanumeric key that identifies the request to initiate the automation. If the API receives multiple requests within 24 hours that contain the same `fileTransferLocationKey`, `fileName`, `relativePath`, and `deduplicationKey`, it ignores all requests after the first one. The maximum number of characters in this field is 256.
_Example_
```
{
"fileTransferLocationKey": "S3_FTL",
"filename": "new_registrations.csv",
"relativePath": "marketing/2025_09_15",
"deduplicationKey": "599393a2c526c680119d84155d90f1e5"
}
```
### updateAutomationTriggerRequestBody
* `isActive` (_boolean_) The status of the automation trigger.
### getTriggerStatusResponseBody
* `triggerdetails` (_object_) An object that contains the status of the trigger request.
* `status` (_string_) The status of the trigger request.
Allowed values: `Deduplicated`, `Error`, `ErrorMultipleAutomationsFound`, `NoAutomationFound`, `Processing`, `Queued`, `Skipped`, `Triggered`.
* `automationDetails` (_object_)
* `automationName` (_string_) The name of the automation.
* `automationExternalKey` (_string_) The user-defined external key of the automation.
* `triggerRequestID` (_string_) The unique ID of the trigger request.
* `resultMessages` (_array of any_) Relevant result messages for the triggered API request. If there are no result messages, the array is empty.
_Example_
```
{
"triggerdetails": {
"status": "AutomationTriggered",
"automationDetails": {
"automationName": "My Import Automation",
"automationExternalKey": "Import_Automation_API_Key"
}
},
"triggerRequestID": "e2dd2b55-431b-404e-b80b-6b1ad6bd527e",
"resultMessages": []
}
```
### getFileTransferActivitiesResponseBody
* `count` (_integer_) The total number of file transfer activities returned.
* `items` (_array of object_) An array of objects. Each object contains details about a file transfer activity.
* `id` (_string_) The unique ID of the file transfer activity.
* `name` (_string_) The name of the file transfer activity.
* `customerKey` (_string_) The unique customer-defined key of the file transfer activity.
* `createdDate` (_string_) The date and time when the file transfer activity was created.
* `modifiedDate` (_string_) The date and time when the file transfer activity was last modified.
* `page` (_integer_) The current page number of results.
* `pageSize` (_integer_) The number of records on each page of results.
### createFileTransferActivityRequestBody
* `customerKey` (_string_) The unique customer-defined key of the file transfer activity.
* `description` (_string_) A description of the file transfer activity.
* `fileSpec` (_string_) The file specification of the file transfer activity.
* `fileTransferLocationId` (_string_) The ID of the file transfer location of the file transfer activity.
* `isCompressed` (_boolean_) Indicates whether the file transfer activity is compressed.
* `isEncrypted` (_boolean_) Indicates whether the file transfer activity is encrypted.
* `isFileSpecLocalized` (_boolean_) Indicates whether the file transfer activity is a localized file transfer activity.
* `isPgp` (_boolean_) Indicates whether the file transfer activity is a PGP file transfer activity.
* `isUpload` (_boolean_) Indicates whether the file transfer activity is an upload.
* `maxFileAge` (_integer_) The maximum file age of the file transfer activity.
* `maxFileAgeScheduleOffset` (_integer_) The maximum file age schedule offset of the file transfer activity.
* `maxImportFrequency` (_integer_) The maximum import frequency of the file transfer activity.
* `name` (_string_) The name of the file transfer activity.
* `publicKeyManagementId` (_integer_) The ID of the public key management of the file transfer activity.
_Example_
```
{
"name": "Test Encryption",
"description": "This file transfer activity is to test PGP encryption.",
"customerKey": "b7d1949c-cfaf-4d74-97f6-e2b2da521b56",
"fileSpec": "test-2.txt.pgp",
"isEncrypted": true,
"isCompressed": false,
"maxFileAge": 0,
"maxFileAgeScheduleOffset": 0,
"maxImportFrequency": 0,
"fileTransferLocationId": "1f91eb52-9a28-4469-8808-accdc4325ced",
"isUpload": false,
"isPgp": false,
"isFileSpecLocalized": false,
"publicKeyManagementId": 1234,
"createdDate": "2023-07-20T10:45:19.5Z",
"modifiedDate": "2023-07-20T10:45:19.5Z"
}
```
### createFileTransferActivityResponseBody
* `customerKey` (_string_) The unique customer-defined key of the file transfer activity.
* `description` (_string_) A description of the file transfer activity.
* `fileSpec` (_string_) The file specification of the file transfer activity.
* `fileTransferLocationId` (_string_) The ID of the file transfer location of the file transfer activity.
* `id` (_string_) The unique ID of the file transfer activity.
* `isCompressed` (_boolean_) Indicates whether the file transfer activity is compressed.
* `isEncrypted` (_boolean_) Indicates whether the file transfer activity is encrypted.
* `isFileSpecLocalized` (_boolean_) Indicates whether the file transfer activity is a localized file transfer activity.
* `isPgp` (_boolean_) Indicates whether the file transfer activity is a PGP file transfer activity.
* `isUpload` (_boolean_) Indicates whether the file transfer activity is an upload.
* `maxFileAge` (_integer_) The maximum file age of the file transfer activity.
* `maxFileAgeScheduleOffset` (_integer_) The maximum file age schedule offset of the file transfer activity.
* `maxImportFrequency` (_integer_) The maximum import frequency of the file transfer activity.
* `name` (_string_) The name of the file transfer activity.
* `publicKeyManagementId` (_integer_) The ID of the public key management of the file transfer activity.
* `createdDate` (_string_) The date and time when the file transfer activity was created.
* `modifiedDate` (_string_) The date and time when the file transfer activity was last modified.
### getFoldersResponseBody
* `count` (_integer_) The total number automation folders returned.
* `items` (_array of object_) An array of objects. Each object contains details about a folder.
* `categoryId` (_integer_) The unique ID of the folder.
* `categoryType` (_string_) The type of folder. For automation folders, the value is `automations`.
* `hasChildren` (_boolean_) Indicates whether the folder has child folders. If the value is `true`, the folder has child folders.
* `name` (_string_) The name of the folder.
* `parentId` (_string_) The unique ID of the parent folder.
* `page` (_integer_) The current page number of results.
* `pageSize` (_integer_) The number of records on each page of results.
### getFtpLocationsResponseBody
* `count` (_integer_) The total number of FTP locations returned.
* `items` (_array of object_) An array of objects. Each object contains details about an FTP location.
* `id` (_string_) The unique ID of the FTP location.
* `name` (_string_) The name of the FTP location.
* `locationTypeId` (_integer_) The type of FTP location.
* `locationUrl` (_string_) The URL of the FTP location. This property is omitted for the Marketing Cloud Engagement Enhanced SFTP service. Possible values are `0` (ExactTargetFTPSiteImport), `1` (ExternalFTPSite), `2` (ExternalSFTPSite), `3` (ExternalFTPSSite), `4` (SalesforceObjectsAndReports), `5` (Safehouse), `6` (ExactTargetFTPStieExport), `7` (OracleObjects), `8` (ExactTargetLegacyImport), `9` (ExactTargetFTPExtSite), and `10` (ExternalSignedHttpsSite).
* `page` (_integer_) The current page number of results.
* `pageSize` (_integer_) The number of records on each page of results.
### getScriptsResponseBody
* `count` (_integer_) The total number of automation scripts returned.
* `items` (_array of object_) An array of objects. Each object contains details about a script.
* `ssjsActivityId` (_string_) The unique ID of the SSJS activity.
* `name` (_string_) The name of the script.
* `key` (_string_) A user-defined key for the script.
* `description` (_string_) A description of the script.
* `script` (_string_) The script code.
* `categoryId` (_integer_) The ID of the category that the script belongs to.
* `createdDate` (_string_) The date and time when the script was created.
* `modifiedDate` (_string_) The date and time when the script was last modified.
* `page` (_integer_) The current page number of results.
* `pageSize` (_integer_) The number of records on each page of results.
### stepsArray
An array of objects. Each object contains details about a step in the automation.
Array of `object`.
* `activities` (_array of object_) An array of objects. Each object contains details about an activity in the step.
* `activityObjectId` (_string_) The unique ID of the activity object.
* `displayOrder` (_integer_) The position of the activity in the step.
* `id` (_string_) The unique ID of the step in the activity object.
* `name` (_string_) The name of the activity.
* `objectTypeId` (_integer_) The type of activity.
* `id` (_string_) The unique ID of the step.
* `name` (_string_) The name of the step.
* `step` (_integer_) The position of the step in the automation.