Best Practices for Importing Interaction Contact Data into SAP Marketing Cloud
24 min read
This article extends the existing documentation by providing examples and use-cases, but does not replace or repeat information already documented in the official SAP API documentation.
In this article, we explore examples of importing Interaction Contact data into SAP Marketing Cloud. Integration of SAP Marketing Cloud and most other SAP products such as SAP S/4HANA, SAP C4C, SAP Commerce Cloud, etc. is typically performed using SAP Integration Suite which provides easy to implement out-of-the-box integration packages. In this article we will show examples of some of the other options.
Table of Contents
- Interaction Contact Data
- Creating an Interaction Contact in SAP Marketing Cloud
Interaction Contact into SAP Marketing Cloud using API
- Import Data using the Contact API
- Update Contact
The focus of this article is to show examples of importing Interaction Contact data into SAP Marketing Cloud using Version 4 of the Contact API and explore its functionalities. Along the way, we will look into some related information such as basic concepts, Contact Data Model, APIs, and alternative to using API to import data. Please see following article for examples using older version of the Contact API:
Please watch the following video on what's new in SAP Marketing Cloud Version 1008:
Interaction Contact Data
Interaction Contact is a generic term to group all natural persons (contacts, consumers, or suspects), companies and “unknowns”, who interact with your company. In SAP Marketing Cloud, the core master data for all Interaction Contacts is referred to as a Contacts. One way to think if it is when Interaction Contact Data is imported into Contacts object in SAP Marketing Cloud. Please see following article for more detail:
Basic Concepts and Data Structure
To better understand the best practices of Contact Data Load, it is important to review some basic concepts of how contact data is handled in SAP Marketing Cloud.
In SAP Marketing Cloud, a contact is identified by an Origin (ID Origin) which is a field defied manually in Marketing Cloud identifying the unique source of data (eg. ERP, Facebook, Commerce), and a Contact ID (Email Address, Commerce Customer ID) which identifies the contact in the Origin system. Origin ID refers to the combination of the Origin and the Contact ID which is used to Match and Merge contacts automatically. Please see following article for more detail:
You can also run Match and Merge activity by manually running an application job from the "Marketing Application Jobs" app:
SAP Marketing Cloud collects bits of information about an Interaction Contact from various sources (Origin: CRM, Social Media, Commerce) to help perform more informed targeted campaigns. To do so, SAP Marketing Cloud builds a master record of a single contact with the best available information from various sources. This record is referred to as the Best Record or the Golden Record. Note that information not used in the Best Record is also kept as Facet Data identified by Origin ID.
In the following example, you can see how a Golden Record/Best Record is built using information from three different sources: ERP, Facebook, and Web Shop. Note that the priority predefined in the system determines which source is valued more when building the Best record.
This feature is new in SAP Marketing Cloud version 2008. In B2B scenario, a contact often works with more than one company. A Contact can have multiple relationships to one account or relationships to several different accounts, each one using a different channel of communication. Following image shows how a contact, Peter Smith, is related to three different Corporate Accounts:
In SAP Marketing Cloud, accounts, just like all other Interaction Contacts, are stored as Contacts. Therefore, the relationship is built between two Contacts one of which must be a Corporate Account. Contact-to-Account Relationships can be defined during contact data import and can be used to create more effective target groups for campaign:
To use this feature, you must use Marketing Area separation. You can find more detail on Marketing Area here .
The Contact object comes with out-of-the-box fields, (Contact ID, Date of Birth, Email, Language, etc.) that can be mapped to fields from Customer data source such as ERP. The data format, type and length of these out-of-the-box fields can not be changed. As part of SAP Marketing Cloud Extensibility, the Custom Fields and Logic functionality allows you to create source fields that can not be mapped to out-of-the-box fields.
You can create a custom field by going into the Custom Fields and Logic application and clicking on the "+" sign. In the following example, "YY1_ShoeSize" is the technical name for the custom field being created which mush be used during data import and mapping.
Please see this article for more detail on Extensibility. Note that custom fields must be made visible to APIs to be able to import data. See following two articles:
Browsing Contact Data in SAP Marketing Cloud
In SAP Marketing Cloud, there are several applications available for browsing Contact data. From your Marketing Cloud "Home Page", search for Contact:
There are two options for individual Contact display: "Inspect Contact" page and "Contact Profile" page.
You can use the "Contacts" app to look for individual contacts, create Contact, open "Contact Profile". This app is useful for filtering contact data by various parameters. "Browse Contact Origin Data" can be used to display distribution of all contacts according to their Origin IDs. "Manage Contact" app is used to display all contacts in a table; this app also allow you to create a contact and import contacts from a CSV file. "Inspect Contact" is used to look for a contact using "Contact ID", display all available information related to the contact, and Download contact's Origin data. You can also open "Contact Profile" from this page.
The "Contacts and Profile Overview" is the dashboard for Contacts. It displays contact's overall activities and various analytics. It also has a quick links local application as well as external applications such as SAP Analytics Cloud.
Click here to find more information on various features of Contacts in SAP Marketing Cloud.
Creating an Interaction Contact in SAP Marketing Cloud
There are three ways to create a Contact in SAP Marketing Cloud:
Using the Create option of the "Contacts" app in SAP Marketing Cloud described in section "Browsing Contact Data in SAP Marketing Cloud" above.
In the Contacts or Manage Contacts app, choose Create and enter the contact data in the dialog box. At a minimum, you must enter a first name, last name, country, and an email address. (For manually created contacts, the Is Consumer business relationship is set to true, and Origin of Contact is set to SAP_MANUAL ( Locally Edited Data) .
Save your entries.
Note that this method to import data is only used for test purposes, and not recommended for productive system. Please see the Application Guide for more detail.
Using the Data File Load app.
This method allows you to upload data from a CSV or XLSX file. Watch this short helpful video on how to use the Data File Load app. The app allows you to map fields. You can download the sample files to help minimize error correction. The app is useful for loading few thousands records, and also to test format of data before finalizing a CSV that is to be loaded from a SFTP server using API described in the next option.
The older "Import Data" app is being deprecated and not recommended.
Using APIs and ODATA service.
SAP Marketing Cloud has several APIs that uses ODATA service to import data directly from source system as long as the source systems Web services and is able to send data in XML, CSV or JSON format. Following APIs are available for importing Contacts:
API_MKT_CONTACT_SRV (Scenario ID: SAP_COM_0207): The primary API used to import and update Contact Master Data. This service should be used for reading and writing master data about natural persons only. It offers a new way to import n:m relationship data. Email, phone, mobile and fax IDs are now imported as AdditionalID entities. This comes with version 004 of the Contact API. Click here for API References:
API_MKT_INTERACTION_CONTACT_SRV (Scenario ID: SAP_COM_0207): This should only be used in exceptional cases, as it has a limited subset of attributes, common to both natural persons and corporate contacts. Click here for API References. Business Scenario:
CUAN_BUSINESS_PARTNER_IMPORT_SRV (Scenario ID: SAP_COM_0017): It is used in marketing-driven and sales-driven processes to replicate data from SAP ERP, SAP S/4HANA Cloud or SAP S/4HANA On Premise to SAP Marketing Cloud interaction contacts. Click here for API References.
- API_MKT_CORPORATE_ACCOUNT_SRV (Scenario ID: SAP_COM_0207): This API is to be used for reading
and writing master data about Corporate Accounts only. Corporate accounts are companies or
organizations that interact with your company. Click here for API References. Business scenario:
Although different API can be used to import Interaction Contact data based on the source system type and data structure, in SAP Marketing Cloud the purposes is always to build a Golden Record or Best Record.
Importing Interaction Contact into SAP Marketing Cloud using API
In this section we will explore examples of importing interaction contact data into Marketing Cloud using the APIs described above. We will be using postman to make API calls. Here is an example of how to use postman to test API.
Import Data using the Contact API
Step #1: Create Communication User, Communication Scenario and Communication Arrangement in SAP Marketing Cloud
The APIs can be enabled in SAP Marketing Cloud by create a Communication User for access, Communication Scenario for the specific integration, and a Communication Arrangement that binds them together and enables necessary services. Please see following article for more detail:
The above process will help generate a User name and Password for inbound communication to your SAP Marketing Cloud instance and API URLs:
Step #2: Data Mapping
It is recommended that only data important for marketing purpose are imported into SAP Marketing Cloud instance. Following are a list of reasons why you might want to import a field into Marketing Cloud:
Segmentation will be performed on the field to generate a target group.
- Field is necessary for identifying a contact or for integrating with an external source
Field is necessary for personalized email campaign
Field is necessary for analytics. Note that analytics capability in SAP Marketing Cloud is limited. We recommend using SAP Analytics Cloud which can be integrated with SAP Marketing Cloud. If you are using SAP Analytics Cloud, fields that will only be used for analytics, does not need to be imported into SAP Marketing Cloud.
Field is necessary for scoring or sentiment analysis. Please see Advanced Analytics for SAP Marketing Cloud.
Please see this short video on planning and configuring the contact data load. Also see " Build Your Technical Architecture for SAP Marketing Cloud " for more detail on architecture planning.
SAP Marketing Cloud comes with predefined fields for the Contact Object. It also allows you to create custom fields, logic and objects. Because each customer's requirement is unique, a proper data mapping exercise is necessary for using SAP Marketing Cloud effectively. Data mapping activities involve following steps:
Identify all source systems (ERP, Facebook, Web Store, etc.) from which data will be imported to SAP Marketing Cloud
Map Origin (ID Origin) to Sources: use existing "Origin" (ID Origin) or create Origin for each data source. Note that "Origin" for some common integration scenarios (S4HANA, Facebook, Twitter) are predefined in SAP Marketing Cloud.
Identify all fields from each source that need to be imported into SAP Marketing Cloud.
- Perform initial mapping of source fields with existing fields in SAP Marketing Cloud. Note that you can import most fields as string in SAP Marketing Cloud, but the length of the field in SAP Marketing Cloud must be greater than or equal to the length of the field in source system.
- Create custom fields and object for fields and objects that are not available in SAP Marketing Cloud.
Map fields from source systems to custom fields in Contact object in SAP Marketing Cloud.
The complete list of available fields for each API can be found in SAP Marketing Cloud help site or API resources site, but the best way to collect the list of fields is by looking at the API metadata. The list will also include any custom fields that you created. Example Service URL to collect metadata:
Examples of API metadata
- Available fields for Contact API: API_MKT_CONTACT_SRV_V4.xml
- Available fields for Interaction Contact API : API_MKT_INTERACTION_CONTACT_SRV_V3.xml
- Available fields for Business Partners API: CUAN_BUSINESS_PARTNER_IMPORT_SRV.xml
- Available fields for Corporate Account API: API_MKT_CORPORATE_ACCOUNT_SRV_V3.xml
Step #3: Define Data Model and Payload
Once data mapping is complete, you can define the data model which involves defining format of the JSON or XML data to be sent to SAP Marketing Cloud. Contact master data consists several entry sets. You can import all at once or import ContactOriginData first and then updated Contacts with rest of the entry sets in any order.
Following is an example of data format for a Contact with We also included examples of Permissions, Subscriptions and Marketing Attributes. This contact can be updated using any of the IDs defined:
Following is a payload example of a ContactOriginData which consists of the basic information about the contact and Marketing Area:
Following is a payload example of Origin IDs for the above contact. Note that there are 7 IDs: 1 email address, 2 phone numbers, a Facebook and a Twitter handle, and C4C and SAP Commerce IDs.
Following is a payload example of Marketing Permissions and Subscriptions for above IDs:
Following is an example payload for few Marketing Attributes for the above contact:
Step #4: Create Contact
The above contact can be created in a SAP Marketing Cloud instance using a POST method API call to https://<Server>:<Port>/sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/$batch
Note that the permissions and subscriptions are updated accordingly:
Now that the contact is created, we can update contact with additional data.
Following payload updated the contact with data from Twitter, Facebook and SAP C4C. Note that this is just an example and in a real implementation scenario, customers are expected to use the out-of-the-box API packages available in SAP Integration Suite API Hub.
The updated contact looks like following:
As we expected, the contact's Best Record is updated according. In this case we collected custom field Favorite Music from user's Facebook account and it is updated in the profile. The user used different names in his social media, but because Commerce Origin has higher priority, only the name from that source is used to build the Best Record:
Example of Contact-to-Account Relationships
In a B2B scenario, contacts can have multiple relationships to one account or relationships to several different accounts, each one using a different channel of communication. In the following example, we will create two corporate accounts and relationships with the contact we created above.
Create Contact to Account relationship
Following payload creates two relationships with two existing Corporate Accounts in the system.
As expected, following two relationships are build with existing Corporate Accounts: Tom Hauser and Marie McNeel:
Available Business Partner Relationship Categories in SAP Marketing Cloud:
|BBP002||Invoicing Party Rel.|
|BUR001||Contact Person Rel. ship|
|BUR002||Shared Living Arrangement|
|CHM005||Resp. Partner Contact|
|CRME02||Trader - End Customer|
|CRME03||Service Center Relship|
|CRMH02||Ship-To Party Relship|
|CRMM01||Alternative Payer Relship|
|CRMM03||Corr Recipient Relship|
|CRMM04||Dunning Recipient Relship|
|CRMS02||Manager for Entitlements|
|FI0300||Altern. dunning recipient|
|FS0030||Borrower Entity Member|
|FSB001||Privat Co. with partners|
|UKM001||CM Account Hierarchy|
Click here for information Mandatory and Optional Mappings.
For standard integration scenario between SAP Marketing Cloud and other SAP Products as well as some non-SAP products, it is recommended to use SAP Integration Suite.
SAP Integration Suite provides out of the box integration scenario which is easy to configure. Please see following article for help with the cloud integration capability in SAP Integration Suite:
The Contact object is the most important object in SAP Marketing Cloud. It is important to identify value adding fields and only store those on SAP Marketing Cloud. Importing Contacts without proper data modeling and data mapping might result into unnecessary anonymous contact which might not be useful for campaign. Before importing contacts data to SAP Marketing Cloud it is highly recommended to make yourself familiar with the APIs available as well as the configuration needed.