Custom Activity Configuration

For simplicity, the documentation mostly refers to custom activities. In Journey Builder, custom events and custom activities use the same framework, so building either object follows the same structure. For event-specific instructions, see Considerations for Building Custom Activities.

PropertyData TypeRequiredDescription
workflowApiVersionStringYesProperty that tells Journey Builder which version this custom activity uses. Use the latest version where possible, though the API provides backwards compatibility. Accepted values are 1.1, 1.0, and 0.5.
metaDataObjectYesObject containing UI-only values that help you identify and categorize each custom activity. Third-party sources pass more properties as applicable.
  • icon - String representing the icon for this activity. Displays what is in metaData.icon in config.json. If not provided, Journey Builder looks for /icon.svg at the root of the endpoint URL. If icon.svg doesn’t exist, it looks for /icon.png. If /icon.png doesn’t exist, a default icon is displayed.
  • category - String representing the type of activity. This value must include one of the Marketing Cloud-provided activity category types:
    • message
    • customer
    • flow
    If the call includes an invalid or missing category value, the activity falls under the 'Custom' category. This value overrides the category selected in the installed package.
  • expressionBuilderPrefix - Use this field to assign custom activities a pre-determined string prefix in the expression builder for decision split. Defaults to Custom Activity if not provided. Pass this field in through the config.json file or include it in the custom activity payload.

    The prefix allows you to easily identify and categorize custom activities. For example, the prefix for Sales Cloud activities could be the object configured for a given activity.

  • isConfigured - Optional boolean value. If true, the activity is marked as configured when it’s dropped on the canvas.
  • configurationDisabled - Optional boolean value. If true and metaData.isConfigured is also true, the activity configuration button is disabled.
  • configOnDrop - Optional boolean value. If true, the activity configuration opens when the activity is dropped on the canvas.
typeStringYesString property representing the type of activity. This value must include one of the Marketing Cloud types or match a valid defined custom C# activity. Valid Marketing Cloud value types include:
  • MultiCriteriaDecision
  • DataExtensionUpdate
  • EngagementDecision
  • randomSplit
  • Wait
  • Rest
langStringYesUsed to define i18n strings. Each entry must match a Marketing Cloud-supported internationalization code, based on two-letter ISO 639-1 standard. Examples: en-US for American English, pt-BR for Portuguese Brazilian, and so on. See the Internationalize Branch Labels section in Go Further with Custom Activities.
  • name - Name the activity something descriptive, such as Send an Email, Send a Text, or Create Salesforce Lead, that displays in the activity list on the Journey Builder canvas. For simplicity, give the activity the same name you used when registered the endpoint in the installed package in Marketing Cloud.
  • description - Description of the activity.
argumentsObjectYesContains information sent to the activity each time it executes. See Data Binding for more information on formulating inArguments and outArguments.
  • execute - The API calls this method for each contact processed by the journey.
  • execute.inArguments - Any static or data bound value configured for the activity. By default, the config.json file sets these arguments. Or you can add inArguments at configuration time.
  • execute.outArguments - Key and value pair for each field expected in the response body of the request
  • execute.timeout - How long, in milliseconds, before each rest activity in the journey times out. Must be from 1,000 milliseconds to 100,000 milliseconds. Default is 20,000 milliseconds.
  • execute.retryCount - How many times to retry each rest activity in the journey after the rest activity times out. Must be from 0 to 5. Default is 0.
  • execute.retryDelay - How long, in milliseconds, to wait before each rest activity in the journey is retried. Must be from 0 milliseconds to 10,000 milliseconds. Default is 1,000 milliseconds.
  • execute.concurrentRequests - How many rest activities to run in parallel. Must be from 1 to 10. Default is 5. Before you use concurrent requests, test the scalability and performance of the target site. If you observe increased gateway errors or timeouts, consider adding retry and increasing the timeout value. To enable concurrent requests, contact Marketing Cloud Support.
  • execute.url - Endpoint used to execute the journey
configurationArgumentsObjectYesObject containing information that relates to this instance of the activity. All configuration arguments except publish are optional.
  • applicationExtensionKey - This read-only value is auto-assigned to custom Journey Builder activities and events when they’re created and is called Unique Key in Marketing Cloud Setup. If it’s correct, Journey Builder overrides the applicationExtensionKey in the config.json, so we recommend leaving it out.
  • save - Endpoint that receives a notification when a user saves the journey.
  • publish - Endpoint that receives a notification when a user publishes the journey.
  • unpublish - Endpoint that receives a notification when a user unpublishes the journey.
  • validate - Endpoint that receives a notification when a user performs some validation as part of the publishing process.
  • stop - Endpoint that receives a notification when a user stops any active version of the journey. The notification is for that particular version.
  • TestSave - Endpoint that receives a notification when a user saves the journey and publishes while in Test Mode. Unless this configurationArgument is included, notifications don’t send to endpoints when a journey is published in Test Mode.
wizardStepsArrayNoContains an array of objects that define the steps that the user navigates through when configuring the custom activity. Each object follows this format:

{ "label": "Step 1", "key": "step1", "active": true }
  • label - The text displayed in the wizard at the top of the configuration screen. This value uses internationalized text when associated with the i18n key defined in the config.json's lang object.
  • key - A unique identifier for the step. customActivity.js uses this key to determine what step to show when the user navigates to a new step.
  • active - Determines whether to show the step in the configuration flow. This setting defaults to true.
userInterfacesObjectYesContains endpoints and UI configurations for the activity's user interfaces: the configuration window, running mode hover, and running mode details window.
  • configModal - Required UI object used to configure the activity. See the Load Custom UI for Activities on Running Journeys section in Go Further with Custom Activities for an example.
  • configModal.url - Endpoint for the UI displayed to marketers while configuring this activity. Defaults to index.html.
  • configModal.height - Property that defines the height of the iframe containing the configuration UI.
  • configModal.width - Property that defines the width of the iframe containing the configuration UI.
  • configModal.fullscreen - If true, forces the configuration UI to take up the entire screen. Defaults to false. This parameter overrides any defined height and width.
schemaObjectNoObject mirrors the activity configuration from the top level of the config.json file and specifies schema information about in and out arguments. Schema objects follow this pattern:


"dataType": MC data type,

"isNullable": Boolean,

"direction": "in" or "out",

"access": "visible" or "hidden"


The context of the call implies the direction of the arguments in the schema, making this value optional. Any provided value must match the context. You can’t include a null value for any declared outArguments, as the call requires these values. Therefore, assume isNullable to be false. For all access property parameters not set to visible, subsequent expression builders don’t show this out argument.