Setting Up & Using External Activity via the API

External activity provides marketers with a way to use all their prospect engagement to drive their marketing automations, helping them to send the right message at the right time. Use the Salesforce and Account Engagement APIs together to submit external activity to Account Engagement. This guide walks through setting up Extension and Activity types, how to submit activity, and the considerations for using External Activity via API. An extension represents a service that generates activity. Activity types are prospect engagement types that are useful for automation. For example, an extension can be an integration with a webinar service, and the activity types can be registered for call, attended call.

A common use case for this setup is when you want your integration to manage the allowed activity types to ensure that the activities that are submitted are consistent. There are three main components to external activity: an extension, which represents an integration, the activity types, which are the types of engagement types that can be submitted, and the business unit assignment.

The Account Engagement and Salesforce APIs use Salesforce OAuth to authenticate with a Salesforce SSO User. Learn more in Authentication.

To access the Account Engagement API and the Tooling API, make sure that the appropriate OAuth Scopes are set up in your connected app:

• Access Account Engagement services (pardot_API)
• Manage user data via APIs (API)

We also recommend adding the Perform requests on your behalf any time (refresh_token, offline_access) scope. This scope lets you use the refresh token flow to get a new access token as they expire and minimizes the number of times you must authenticate.

Consider allowing the customer's Salesforce Admin to run the setup without persistent authentication and name a different user for execution to help minimize risk around data access.

Use metadata to define extensions and allowed activity types. For example, you want to integrate a webinar service. The extension is the webinar service name, and the activity is prospect events like attended, registered, and so on.

Use the Salesforce Tooling API to systematically set up the extension and activity types metadata. In this guide, we use the REST Tooling APIs.

Keep these considerations in mind as you set up external activity submissions.

• You need Salesforce Admin user, or you can set up a Marketing Admin User with API access to use the Tooling API.
• Instead of using the API to set up external activity, a Salesforce admin can create the Marketing App Extensions & Activity Types that are required. However, it’s important the naming is consistent with what is being submitted in the execution API calls for the activity to be accepted.
• There’s limit on the number of extensions, and the number of activity types per extension. Write clear error messages so users are informed when they reach the limit. See Considerations for Using External Activities in Salesforce Help for more information.
• A Marketing App Extension must be assigned to a Business Unit to use it in the business unit.
• If you’re a third-Party service and building a generalized integration, then consider ways to ensure your extension name is globally unique. For example, add a random number to the name to avoid potential conflicts if an admin already set up an extension for your service.
• To activate a Marketing App Extension and related Market App Extension Activity Types for submitting activity and use them in automations, you must meet these conditions:
  • The isActive field for Marketing App Extensions is set to true.
  • The isActive field for each Marketing App Extension Activity type is set to true.
  • The extension is assigned the correct business unit.
  • If there are manual steps in between setup and execution, then recommend to not fully activate the extension. To avoid confusion, activate the extension when you're ready to start submitting the activity.

Use these endpoints to set up the extension and activity types.

Use this metadata when setting up external activities.

In this example, we set up a webinar extension with a registered type that is used by the HappyHomeTX Account Engagement Business Unit.

1. Authenticate to the Salesforce API.
2. Make your request: Create an extension for a webinar service and set IsActive to true. We recommend naming it after the service to make it easy to recognize the source.

Response:

3. Take note of DeveloperName, it’s used to submit activity.

1. Add an activity type. This example adds an activity type to the extension created in Step 1: Create the Marketing App Extension. Request Example:

Response Example (Status: 201 Created):

2. Take note of DeveloperName for each of your activity types.
3. Set IsActive to true when ready to submit activity.

1. To get your business unit IDs, you can either use query, or find them on the Business Unit Setup screen in Salesforce. This example uses a request to query the Salesforce org for associated Account Engagement Tenants.

Response Example (Status 200)

2. Take note of the Id value for the PardotTenant, it's the business unit ID.

Make the request to assign. This example request assigns the Webinar extension to the HappyHomeTX.

Response Example

Record the business unit IDs. They’re used to submit activities.

After extensions are set up, you can submit the activities as they occur using the Account Engagement API.

Use the Account Engagement external activity endpoint (/api/v5/external-activities) to submit activity to Account Engagement for use within Automations. Activity can be only submitted for the Extension / Activity types that were set up. The value provides a way to distinguish one instance of the activity from another.

An activity submission looks like this:

1. A prospect registers for a webinar in the Webinar Service creating an activity.
2. The activity is submitted to Account Engagement using the external activity endpoint. Example Request

Example Response (Status 202 Accepted)

Keep these considerations in mind when submitting activity:

• Consider the limits for this endpoint, and account for scenarios when a limit is reached. See Considerations for Using External Activities in Salesforce Help for more information.
• Recommend to not authenticate again when submitting a request and only do so when a token expires.
• If the extension or activity type is changed to isActive=false, then activity can no longer be submitted. An admin can change these settings in the UI.
• Activity can be submitted only to the assigned business unit. If the business unit assignment is changed, it can affect your integration.
• The integration user needs the Account Engagement Permission for write access to prospects.