Account Engagement API Quick Start

This tutorial walks you through a few real-life tasks so you can start automating and extending Account Engagement. In this guide, we implement authentication by using an OAuth2.0 flow, and then make some example calls and complete a basic task.

Before you begin, make sure that you have:

• A Salesforce admin to create an external client app and gather information.
• A Salesforce user with single sign-on (SSO) enabled for Account Engagement.
• A configured Account Engagement business unit.
• Selected which OAuth flow works best for your case. This tutorial uses the Web Server OAuth flow.

This tutorial requires knowledge of external client apps and authentication. If you aren't familiar with these topics, review the concepts in External Client Apps first.

After you familiarize yourself with the basics, come back to this tutorial.

To authenticate Account Engagement API requests, you must use an SSO-enabled Salesforce user who has Account Engagement access and an OAuth flow with an external client app.

The first step in authentication is creating an external client app. An external client app is a framework that enables an external app to integrate with Salesforce by using APIs and standard protocols like OAuth. External client apps use these protocols to authenticate, authorize, and provide SSO for external apps. To put it simply, an external client app represents an integration. See External Client Apps.

To set up an external client app, have a Salesforce admin follow these steps:

1. From Salesforce Setup, in the Quick Find box, enter External Client Apps, and then select External Client Manager.
2. Click New External Client App.
3. Configure the external client app.
4. Name the external client app.
5. Add the email address for the admin who manages Agentforce.
6. From the Distribution State picklist, select Local.
7. In the API section, select Enable OAuth Settings.
8. Enter a callback URL. The callback URL is used to redirect users after authentication in browser-based flows. This example uses https://my.example.com/myapp. If you use a browser-based flow, such as Web Server Flow or User Agent Flow, the URL must match the URL you pass as a callback to OAuth endpoints. If you aren’t using a browser-based flow, the URL isn’t used.
9. To give the app access to Account Engagement, under Selected OAuth Scopes, add Manage Pardot services. For more complex scenarios, such as using refresh tokens, select other scopes as well.
10. Click Create.

Now that you have an external client app, gather some important information you need handy to finish setting up authentication.

The primary details are:

• External Client App Consumer Key: a unique identifier for your external client app.
• External Client App Consumer Secret: a password for the external client app.
• Business Unit IDs: Because a Salesforce org can have multiple business units, the ID routes the API request to the correct business unit. You need the ID even if you have only one business unit.
• Salesforce User: A Salesforce user with SSO enabled for Account Engagement.

Because all of this information is sensitive, carefully consider how to share these details with other team members securely.

1. From Salesforce Setup, in the Quick Find box, enter External Client, and then select External Client Manager.
2. Go to your external client app and select Settings.
3. In the OAuth settings, click Consumer Key and Secret.
4. Copy your consumer key.
5. Reveal and copy your consumer secret.

1. From Marketing Setup, in the Quick Find box, enter Pardot, and then select Pardot Account Setup.
2. Copy the business unit ID for the Account Engagement instance you want to use.

For the integration user, we recommend that you create a unique user for each specific app integration. The user must be SSO-enabled and have access to Account Engagement.

Salesforce has several OAuth flows to meet your unique security and integration needs. In this tutorial, we use the Web Server OAuth flow. This flow is ideal for when you don’t want to store the end user’s credentials in your system. To learn more about your options and how to choose the best OAuth flow for your integration, check out Salesforce OAuth Help Documentation.

1. Have your integration direct the user to Salesforce’s OAuth authorization endpoint:

   https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://my.example.com/myapp

   • Replace CLIENT_ID with your external client app consumer key.
   • Replace https://my.example.com/myapp with your redirect URI.

2. If the user doesn’t have an active session, they’re prompted to log into Salesforce.

3. The user grants the app permission.

4. After the user has logged in and allowed the app, Salesforce redirects you back to the redirect_uri passed in to the authorize endpoint:https://my.example.com/myapp?code=<CODE>

5. Your server-side code exchanges this code for an access token by making a POST request to the Salesforce OAuth token endpoint:

6. After Salesforce validates the external client app credentials and authorization code, the endpoint responds with an access token:

The access token can be used to make calls to the Account Engagement API. The code was exchanged for the access token on the server side and not from the user’s browser. Because of how the code was exchanged, there’s no opportunity for malicious JavaScript to steal the access token.

After you’ve implemented authorization, you can start working with the Account Engagement API.

With the Account Engagement API, your app can access current data within Account Engagement. Through the API, you can perform several common operations on Account Engagement objects including:

• create: Creates an instance of the object with the specified parameters.
• read: Retrieves information about the specified object.
• query: Retrieves objects that match the specified criteria.
• update: Updates elements of an existing object.
• upsert: Updates elements of an existing object if it exists. If the object doesn’t exist, one is created using the supplied parameters.

Developers must authenticate using a Salesforce OAuth endpoint or the Account Engagement API login endpoint before issuing Account Engagement API requests. Refer to the Authentication section for details about this procedure.

Keep in mind a few considerations when you perform requests. For update requests, only the fields specified in the request are updated. All others are left unchanged. If a required field is cleared during an update, the request is declined.

All requests to the API must:

• Use either HTTP GET or POST. Version 5 also supports PUT and DELETE requests.
• Pass the access token in an HTTP Authorization header.
• Pass the Account Engagement Business Unit ID in an HTTP Pardot-Business-Unit-Id header.
• Use the correct URL for your Account Engagement environment.

In this example, we want to get a list of all custom fields in a business unit.

Before you begin, make sure you’ve authenticated and have a valid access token. For simplicity in this example, these calls are written in HTTP.

Let’s break down the call and identify its parts, starting with the uniform resource identifier (URI). GET https://<ENVIRONMENT_URL>/api/<OBJECT>/version/<API_VERSION>/do/<OPERATION>?format=<FORMAT>

• Environment URL: In the example, we use pi.pardot.com, but you use the URL that matches your environment type. Demos, developer orgs, and sandbox environments are hosted on the domain pi.demo.pardot.com. Training and production environments are hosted on the domain pi.pardot.com.
• Object: The object we’re requesting data for. In our example, we’re querying the CustomField object.
• API version: The version of the API you’re using. Here, we use v4.
• Operation: The operation you’re performing. Here, we use query.
• Format: The output format, either XML or JSON. Here, we use json.

Now that we’ve explained the URI, let’s examine the header lines in the call.

• Authorization: Bearer <ACCESS TOKEN> lets Account Engagement know that you’ve authenticated and have permission to access data.
• Pardot-Business-Unit-Id: <BUSINESS UNIT ID> lets Account Engagement know which business unit you want data from.
• Host: The URL for your Account Engagement environment.

The call returns the business unit’s custom fields and their metadata.

Learn more about each object’s fields in the Object Field Reference documentation.

In this example, we create a list for a spring nurturing campaign.

Before you begin, make sure you’ve authenticated and have a valid access token.

We went over the URI and the authorization and business unit headers in the GET example. Let’s cover the other components:

• Content-Type: application/x-www-form-urlencoded: Tells the server what kind of data is included in the request.
• name=Spring Leads Nurture: Sets the internal name of the list to "Spring Leads Nurture."
• title=Spring Leads: Titles the list "Spring Leads."
• description=A list to nurture spring leads: Adds a text description to the list.

When we send this request to the server, Account Engagement responds by creating a list with the criteria that we specified. The response looks like this:

Let’s take the example a step further and add a prospect to our new list. Remember that completing this task changes data in Account Engagement, so proceed with caution.

Before you begin, make sure you’ve authorized and have a valid access token. For simplicity in this example, we make these calls in our command-line interface using cURL.

First, copy the list ID for the list you want to add a prospect to. Then, find the IDs for the prospect you want to add to the list. You can use query on the Prospect object to get ID.

• List ID: 1000
• Prospect ID: XXXXX

Notice that the URI includes the prospect’s ID: XXXXX. When we send this request, Account Engagement adds that prospect to the list with the ID 1000.

It can be helpful to talk to other developers about the problems you’re working on. Connect with like-minded Account Engagement developers by joining a Trailblazer Community Group near you.

• Salesforce Help: External Client Apps
• Salesforce Help: Authorize Apps with OAuth