Getting Started with Marketing Cloud APIs
By: Hunter Dunbar
Tags: Salesforce Development, Marketing Cloud, Salesforce Tools, Postman, Salesforce

Getting Started with Marketing Cloud APIs

Authorization and Exploration with SOAP and REST

Salesforce Marketing Cloud provides a suite of tools that enable organizations to manage customer engagement across a complete customer journey from marketing and sales to commerce and service. Marketing Cloud helps you know your customers, personalize your messages with relevant data, and engage with them across touch points. To provide these solutions, Marketing Cloud logs a wealth of data about customer interactions in application databases. Much of this data is accessible via the Marketing Cloud API.

The following tutorial provides step-by-step instructions for connecting to the Marketing Cloud APIs. Salesforce provides comprehensive documentation of these APIs here: https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/index-api.htm

This tutorial covers three aspects:

· Creating a Connected App in Marketing Cloud Setup

· Obtaining an access token via REST API callouts

· Building SOAP API callouts to Marketing Cloud to interact with a database

Creating a Connected App in Marketing Cloud Setup

The first thing to do is create a Connected App in Marketing Cloud. To do this, follow the instructions in this trailhead:

1. In Marketing Cloud, go to Setup.

2. Click Apps.

3. Click Installed Packages.

4. Click New.

5. Give the package a name and description.

6. Create the package with enhanced functionality.

7. Save the package.

8. Under Components, click Add Component and select API Integration.

9. Select an integration type: a) Server-to-Server with Client Credentials Grant Type OR b) Web and Public App Integrations with Authorization Code Grant Type

10. Set the integration properties, including scopes and the redirect URIs for web and public apps. Use https://127.0.0.1:80/ as a valid redirect URI for local testing.

11. Save the component.

Here’s what your package will look like. (In the screenshot below, we’ve only configured scopes for Subscriber. You’ll probably want to provide more expansive access.)

Obtaining an Access Token

Marketing Cloud requires every request to contain an access token. To do this, make a callout to the Marketing Cloud API. Specifically, make a POST request against a Token endpoint and pass in authorization information from our Installed Package.

1. Create a POST request against the endpoint listed in your Package (created in the previous step). So REST Base URI + “v2/token”.

2. Pass the following JSON payload in the request replacing {{client_id}} and {{client_secret}} with a values from the Installed Package.

Sample JSON payload to return an Access Token.

3. The API will return an access token, scopes that were authorized, a soap instance URL, a rest instance URL, and the number of seconds until the access token will expire.

This access token will be good for 1079 seconds, which is a little over 15 minutes. On subsequent requests before 15 minutes, you will need to obtain a new token. You will have to pass the access token on all requests to the SOAP API endpoints. Let’s talk about SOAP.

Building SOAP API callouts to Marketing Cloud

Once you have our access token, you can build SOAP requests for interacting with the Marketing Cloud database. Building requests can be somewhat challenging, so we will show how to import a WSDL to SOAP API that will prebuild requests templates for you. Then, we will walk through a specific example.

API Exploration with Marketing Cloud WSDL

There are a variety of ways to explore the Marketing Cloud API. For this task, we use the SOAP API.

To execute these steps, install SOAP UI.

The first thing to do is identify the link to our WSDL. Here’s the relevant documentation for this step. Basically, replace the following URL with the domain that can be extracted from our Marketing Cloud package.

1. Here’s the URL template: https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/etframework.wsdl

2. You can find YOUR_SUBDOMAIN on the Installed Packed page listed above. Copy everything after https:// and before .soap.marketingcloudapis.com.

Next, import the WSDL into a SOAP UI project.

1. Click SOAP to create a new SOAP project.

2. Enter a name for the project.

3. Add the URL from above, and click OK.

A new project will be created. The Marketing Cloud API provides templates for a variety of methods for connecting to the UI.

Click on Request 1 to see a sample request. You can save multiple requests for each type of method for future use.

Retrieving data with the SOAP API

Next, we walk through the process for retrieving data via the API. We provide an example of retrieving ClickEvent data using a Retrieve request.

1. Open the Retrieve > Request 1 request.

2. Update the soapenv:Header to include the access token that we pulled in the previous section. The access token should be enclosed in <fueloauth></fueloauth> t

3. Update the soapenv:Body with a RetrieveRequest parameter. The RetrieveRequest parameter should include a ClientId, an ObjectType, and Properties for the object (basically the fields we want to pull).

4. Update the Client ID tag with the Client ID of your Marketing Cloud organization. I found mine here:

Here’s an example request:

Click the green arrow in the top left of the Request modal to execute your query. This will execute the request and return results in the pane on the right.

Here’s what the results will look like:

The SOAP UI is not the only tool that will work for this process. We are now doing most of our requests through Postman. Either tool should work as long as you structure your requests correctly. For more detailed API information, check out Salesforce’s Marketing Cloud documentation, which details all of the methods and objects that you can connect to: https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/index-api.htm

Cervello, a Kearney company is a data and analytics consulting firm and part of Kearney, a leading management consulting firm. We help our leading clients win by offering unique expertise in data and analytics, and in the challenges associated with connecting data. We focus on performance management, customer and supplier relationships, and data monetization and products, serving functions from sales to finance. We are a Salesforce partner and help our clients implement, customize, and optimize the platform into the best solution for their needs.