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 Pardot APIs together to submit external activity to Pardot. 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.

To learn more about external activity, see Salesforce Help.

Authentication

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

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

  • Access Pardot 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.

If you’re a third-party service and building a generalized integration, consider creating a managed package with the connected app. A managed package lets you use one connected app across all of the orgs that use the integration and prevents configuration issues.

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.

Setup

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.

Endpoints and Parameters

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

EndpointDescription
Marketing App ExtensionThe metadata that defines the extension.
Marketing App Extension AssignmentRelates a Marketing App Extension to a Pardot Business Unit. Assignment determines which business units activity can be submitted to, and where the activity can be used in automations.
Marketing App Extension Activity TypeThe metadata to define activity types for an extension.
Pardot TenantThe metadata for the Pardot Business Unit. Use to programmatically identify and assigned business unit ID.

Use this metadata when setting up external activities.

MetadataDescription
DeveloperNameExtension API name. Used to submit an activity.
MasterLabelExtension name shown in the UI.
DescriptionDescription of the extension. Appears in the UI.
IsActiveAvailable for use in automations.

Setup Example

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

Step 1: Create the Marketing App Extension

  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.

Step 2: Create Your Marketing App Extension Activity Types

  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.

Step 3: Find the Business Unit IDs

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

    Response Example (Status 200)

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

Step 4: Assign the Marketing App Extension to Business Units

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.

Submitting Activities

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

Use the Pardot external activity endpoint (/api/v5/external-activities) to submit activity to Pardot 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.

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 Pardot Permission for write access to prospects.

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 Pardot using the external activity endpoint. Example Request

    Example Response (Status 202 Accepted)

  • The extension value in the example is the DeveloperName returned from the Marketing App Extension response.
  • The type value in the example is the DeveloperName returned from the Marketing App Extension Activity Type response.