As a manufacturer, you need to communicate with your customers, who come in all shapes and sizes: dealers, distributors, suppliers and end-users just to name a few. One of tools that can help aid this communication is Marketing Cloud from Salesforce.
Marketing Cloud: In a Nutshell
Marketing Cloud has functionality to address communication needs across channels, such as social, mobile and email interactions. Marketing Cloud also is typically connected to the Sales Cloud CRM from Salesforce. There are times where the default integration between Marketing Cloud and Sales Cloud needs to be extended by leveraging one of the Marketing Cloud APIs.
Case in point: in a recent example with one of our manufacturing clients, the Marketing Cloud subscriber ID was saved within the Salesforce Sales Cloud objects, but we didn’t necessarily have the email address for that specific subscriber. So we needed to use one of the Marketing Cloud APIs to pull back the email address by passing over the Marketing Cloud subscriber ID. This integration kept the two systems of Marketing Cloud and Sales Cloud in sync so that subscription management could be managed effectively in a multi-org Marketing Cloud setup.
4 Benefits of the Marketing Cloud REST API
There are many benefits to the Marketing Cloud REST API. Let’s dive into a few of those and then address how to connect to the REST API.
1. Robust Set of Predefined Endpoints
Marketing Cloud has a long list of endpoints for the API you can view here. Salesforce does a thorough job of explaining what each endpoint does and what values are required. To name a few, some example endpoints include getting an asset by ID and creating campaigns.
Although the endpoints allow for many different interactions to take place, sometimes knowing how to leverage them correctly isn’t always clear. My team wanted to search Marketing Cloud based on the subscriber ID and get back the subscriber Email. After a few attempts, we realized this endpoint POST /contacts/v1/contacts/search was one the one we wanted.
2. Developers Can Define What the Endpoints Make Available
Setting only the fields that the API wants exposed will help protect the data. If more access is needed at another point, that is simple to add, but by limiting what the API can reach within your data, you can prevent users from seeing or changing the data they shouldn’t access.
In my example above, my team only needed read access of the subscriber (contact) object. By limiting it to read-only, we prevented Salesforce users from updating our Marketing Cloud objects, which could have altered data in a detrimental way.
3. Open Data Flow in Both Directions
When adding functionality to either Marketing Cloud or Salesforce, one might find that they need access to data that is only in the other system. Using the REST API allows both pushing data into Marketing Cloud or pulling the data into Salesforce for a fuller data picture in both environments. Maintaining two environments of mirrored data may not be ideal, so the ability to get needed information from the other could help prevent differences across the systems.
In our example, the update from Marketing Cloud to Salesforce was done every few hours, so we did not always have the email for a given ID. To eliminate this issue, we chose to implement the REST API when we need an email address for a contact that had not yet moved over.
4. Error Handling
Marketing Cloud has made sure that if you do not get a good result, the system will send back useful errors. For anyone trying to figure out the API, this is extremely helpful and allows the user to zero in on the problem with the call. These errors help with the body and access to the endpoints. You can learn more about Marketing Cloud’s error page here.
When we were working through our project, we struggled to figure out which would be the fully qualified names for the subscriber ID. The error we received was extremely straightforward “There is no Attribute with FullyQualifiedName ‘Subscriber. Subscriber ID’.” It still took us a while to figure out that we should try Contact ID, but we knew what we should be changing.
How to Connect to the API
- Start setting up the API on Marketing Cloud by creating an installed package. This will generate a Client ID and Secret. See this page for Marketing Cloud documentation explaining how that is done.
-
Next I suggest using a tool like Postman to try out and debug calls out to Marketing Cloud, so you know you have the correct calls when you go to write the code. In Postman, you need to get the Token. This can be done by hitting the request token endpoint with a POST (https://auth.exacttargetapis.com/v1/requestToken). Put your Authorization to no Auth and add in the body the Client ID and Secret using the form-data radio button.
-
Now you are ready to try out your calls! We used a POST to the endpoint www.exacttargetapis.com/contacts/v1/attributes/search. Make sure your Authorization Type is Bearer Token and input the token that you received from the requestToken endpoint. Also add a header for Content-Type setting the value as “application/json”. To retrieve the subscriber email based on the subscriber ID, our body was:
{"request":{"attributes":{"key":"Contact.Contact Key"}},“conditionSet”:{"operator":"Or","conditionSets":[],"conditions":[{"attribute": {"key":"Contact.Contact ID"},“operator”: “Equals”,“value”:{"items":["123456789"]}}]}}Of course the body and the endpoint will differ with the data you are attempting to extract, add or update with the Marketing Cloud API.
- Finally, you are ready to put this call into Apex code! Don’t forget to add the call to get the token, as well as the API call you want to make.
Any Questions?
If you need a hand, feel free to reach out to our team of software engineers anytime. We’re always here to help.
