Coding With Salesforce Marketing Cloud Fuel REST API

The Salesforce Marketing Cloud (ExactTarget) Fuel REST API is lightweight, easy to use, and on its way to full maturity. Development teams are choosing to leverage it more frequently. In the recent past, several of our clients’ development teams encountered hurdles implementing the Fuel REST API within their projects.

This post will get development teams started coding with the Fuel REST API faster and easier than before.

Prerequisites

An API user account must be created with the correct access level to the business unit you will be targeting with your calls.

Process

The REST API uses OAuth. Here’s further info about ExactTarget’s OAuth utilization – https://code.exacttarget.com/apis-sdks/rest-api/using-the-api-key-to-authenticate-api-calls.html

Developers should go here, and click the navigation link on the left (or the button on the lower right) to access the Using App Center to Get an API Key page.

The client’s development team should follow the steps outlined below to secure their client id and client secret values for both their production and testing business unit instances.

Note: when creating these applications, your registration will be bound to a specific business unit that you specify, and you will not be able to redirect your calls to another business unit as you can do with a SOAP API call.

Create an App Center account

You are creating one account. Depending on your use-case, it might make sense to have multiple accounts rather than just one account. This is highly dependent on who will be responsible for managing the application registrations. This account will manage application registrations but is not directly tied to any specific account.

Click the “create account” link just below the Login button.

1. Username – We recommend a username that isn’t specific to an individual
2. Email Address – A unique email address should be used with this account. We recommend one that is not tied to a specific individual. You may want to have this be a distribution group of authorized individuals so that access is not limited to a single user and email box.
3. Password – Your password should Include lowercase, uppercase, number, and special characters, be at least 12 characters in length, and must not contain the username.

App Center: Registration

Make sure to fill out the following fields: first name, last name, company, email, corporate website URL, and please describe how you intend to use the Fuel Platform.

App Center: EULA

Click accept if you agree to the terms.

Create New App

Click on the API Integration template.

Create New API Integration App

Create New API Integration App – Define

1. Name*
2. Description
3. Package* – This is a unique namespace you give to the application. It must be unique but the value you use here is for identification of the app and not tied to anything specific. We recommend a value indicative to its purpose and environment.

Create New API Integration App – Integrate (Ties your app to a business unit)

1. Account* – Select New from the drop-down. If another account is listed in the drop-down that isn’t the one you want to target, click the down arrow and then select New. Select the radio button option Production ExactTarget Account (unless you actually mean to connect to a Sandbox ExactTarget Account – most accounts are not Sandbox configurations).Click the Link to Account button. The Account Integration iframe will pop up at this point. Enter your account credentials (mentioned as a prerequisite above), if prompted. The Account Integration interface will become visible.

Specify the business unit that this application should map to using the drop-down selector. This will bind your application to the business unit. Then click the Integrate button to confirm our business unit selection.

Create New API Integration App – Data Access

For a development/testing business unit, you may want to enable most of the permissions to get started (click Show All to expand all channels option content).  When setting up a production application, you would want to give the least amount of permissions necessary to accomplish the business goal.

1. Channels
2. Contacts
3. Hub
4. Data
5. Assets
6. Automation

Create New API Integration App – Summary

This contains information relevant to your app.

The page should refresh with Client ID and Client Secret now visible in the Authentication and Integration section of the page. Record this information in a secure place. These are the OAuth credentials you’ll need to retrieve an access token, which will allow you to make successful REST or SOAP API calls utilizing OAuth authentication.

Now that your API integration app is set up, you can generate a token and start making REST calls!

Request A Token

Salesforce Marketing Cloud | code @ offers great documentation including an overview, JSON Parameter outline, and usage examples (response and request).

Note: OAuth tokens expire after 60 minutes. New tokens must be generated upon expiration in order to continue making successful calls.

Bonus: Use Your OAuth Token With SOAP API Calls

You can use your OAuth token with SOAP API calls by using the following values in your SOAP header (replace the OAuthToken in this sample with the token you generated):

<oAuth xmlns=”http://exacttarget.com”>

<oAuthToken>36atgcbmx6ax29mn3b3camu</oAuthToken>

</oAuth>

<Security xmlns=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd”>

<UsernameToken>

<Username>*</Username>

<Password>*</Password>

</UsernameToken>

</Security>

</Header>