Skip to Content

How to use the new Contact OData API for SAP Marketing Cloud 1711


Welcome to the blog post of the Expert Services Marketing Practice.

We are happy to share our experience with you around Marketing Integration, Analytics, and Business Technology.

You want to see more? Click here

Table of Content


As you have probably already seen with the new Release of SAP Marketing Cloud there is a bunch of new public APIs available.

You can find the full list on Some of the most important are listed below:

  • Contacts (OData API “API_MKT_CONTACT_SRV”)
  • Interaction Contacts (OData API “API_MKT_INTERACTION_CONTACT“)
  • Corporate Accounts (OData API “API_MKT_CORPORATE_ACCOUNT“)
  • Interactions (OData API “API_MKT_INTERACTION_SRV)

Those APIs offer new features and functionalities like batch support and dedicated services for each business object.

In regards to the different Public APIs for SAP Marketing Cloud the Application help What’s new section for 1711 recommends the following:

“As of this release, we strongly recommend that you use one of these APIs instead of using the OData service CUAN_IMPORT_SRV.”

The statement clearly shows the importance for your projects to get familiar with those APIs.

In this blog post we will pick the new Contact API as an example to learn how to read and write contact data via the Postman Rest Client.

Step 1: Communication Management Setup in SAP Marketing Cloud

In general the communication management setup in SAP Marketing Cloud is always following those 3 steps described here:

  1. Create a communication user
  2. Create a communication system
  3. Create a communication arrangement

Important for the Contact API is that you select in the communication arrangement step the integration scenario: SAP_COM_0207 – Interaction Contact Integration.

For a more detailed information you can have a look at this blog post.

Step 2: Reading Contact Data out of SAP Marketing Cloud

After setting up the communication management on SAP Marketing Cloud we are ready to use any Rest Client or Middleware (like SAP Cloud Platform Integration) to call the Public Contact API with the created communication user.

A good starting point is always to have a look at the official API documentation in the Application help and the information provided via SAP API Business Hub.

In this blog we will focus on the use of Postman as a Rest client which you can download here.

If you follow the documentation you will see that the API provides the following service entities:

  • Contacts

  • AccountTeamMembers

  • AdditionalIDs

  • ContactOriginData

  • MarketingAttributes

  • MarketingAreas

  • MarketingPermissions

This blog is focusing on the ContactOriginData entity but the use of the other ones is very similar to this.

If you want to read contact origin data in SAP Marketing Cloud you can simply use a GET call like this:


Please note that for the GET Method the following requirements are important:

  • Specification of TOP is mandatory (without the TOP paramter your call won’t be accepted –> HTTP response code 400: Bad request)
  • A maximum of 5000 contact origin data entities can be fetched in a single request (a error occurs and your call won’t be accepted –> HTTP response code 400: Bad request)

<yMKT_URL> stands for the URL to your SAP Marketing Cloud System you can use those as parameters via environments in Postman. The complete yMKT_URL should look like this:$top=1

As a result you will get one contact origin data information like the one below:

 <content type="application/xml">
            <m:properties xmlns:m="" xmlns:d="">
                <d:BirthDate m:null="true"/>
                <d:FullName>John Doe</d:FullName>

Beside $top you can use other standard OData Parameters like $filter$select$top$skip$count$inlinecount, and $orderby.

For example to filter in Postman for a specific contact with ID ‘’ you have to use e.g. the following $filter parameters

<yMKT_URL>/API_MKT_CONTACT_SRV/ContactOriginData?$top=10&$filter=ContactID eq ‘’

The steps in Postman are the following:

  1. You have to select GET as the method.
  2. Configure under Authorization tab the Marketing communication user credentials
  3. Insert the call URL for your respective system and contact origin data
  4. Click on send button to push the data to your SAP Marketing Cloud API
  5. Have a look in the response from the system

See the screenshot below for the needed GET call settings.

In this screen you see the system response. If the call is successful you will get a Status 200 OK response.

In the next step we will upload contact origin data to the SAP Marketing Cloud system.

Step 3: Writing Contact Data to SAP Marketing Cloud

For the posting of contact origin data we have to do first a GET call to the SAP Marketing Cloud System to fetch the x-csrf-token value.

In the next step this token can be used to send the POST batch request. If we don’t provide the system with a correct token the system won’t accept our POST call. We will receive a HTTP 403 Forbidden status code and the message: CSRF token validation failed

The reason for the need of this token is the enabled SAP Gateway Cross-Site Request Forgery Protection. For more information have a look at this documentation.

Find some standard technical documentation for API_MKT_CONTACT_SRV via this Link

  • GET Call Steps:

  1. Enter the URL for the metadata call <yMKT_URL>/API_MKT_CONTACT_SRV/$metadata
  2. Select the checkbox ‘GET’
  3. Click on ‘‘Authorization’. Select Basic Auth and enter your user and password of your SAP  Marketing Cloud communication user. The authentication credentials will be base64 encrypted automatically
  4. Click on ‘Headers’ and type in ‘X-CSRF-Token’. Enter ‘Fetch’ as value
  5. After you entered all information your OData metadata call should look similar to the subsequent screenshot
  6. When executing the metadata call with ‘Send’ the system request the data from the SAP Marketing Cloud system and shows the response
  7. When executing the get data call with ‘Send’ the system fetches the CSRF-Token, too.
  8. In the header section of the response you see the CSRF token which you should note down for the following POST statement:
  9. In addition the body of response will show you the metadata of the API:


  • POST Call Steps:

  1. After the CSRF token response from SAP Marketing Cloud the post can be done with the rest client to send data in JSON format
  2. Enter the URL for the post data call <yMKT_URL>/API_MKT_CONTACT_SRV/$batch
  3. Select the checkbox ‘POST’
  4. Be sure to provide the correct Authorization
  5. Enter the CSRF token you requested in the GET call as ‘x-csrf-token’ header value
  6. Setting the ‘content-type’ header as ‘multipart/mixed;boundary=batch’. See screenshot below:
  7. Enter your batch request in the request body

See the following example request body:

Content-Type: multipart/mixed; boundary=changeset_1

content-type: application/http
content-transfer-encoding: binary

PUT ContactOriginData(ContactID='',ContactOrigin='SAP_HYBRIS_CONSUMER') HTTP/1.1
Content-Length: 1035
Accept: application/json
Sap-Cuan-RequestTimestamp: '2018-01-01T12:14:14'
Sap-Cuan-SourceSystemType: EXT
Sap-Cuan-SourceSystemId: HYBRIS
Content-Type: application/json

 "OriginDataLastChgUTCDateTime" : "2017-10-01T13:14:14",
 "CityName" : "Kiel",
 "Country" : "DE",
 "EmailAddress" : "",
 "FullName" : "John Doe",
 "GenderCode" : "1",
 "AddressHouseNumber" : "1",
 "IsConsumer" : true,
 "Language" : "DE",
 "MaritalStatus" : "2",
 "MaritalStatusName" : "Married",
 "ContactPostalCode" : "24105",
 "StreetName" : "Hauptstrasse",
 "GenderCodeName" : "Mr."


9. When executing the POST data call with ‘Send’ you call the Inbound API of SAP Marketing Cloud to create/update contact origin data

10. See the HTTP status 202 accepted response result

Content-Type: multipart/mixed; boundary=96C4D9F1C73250570C81846B54DD8BF21
Content-Length:       411

Content-Type: application/http
Content-Length: 243
content-transfer-encoding: binary

HTTP/1.1 204 No Content
Content-Length: 0
dataserviceversion: 2.0
sap-message: {"code":"HPA_STAGING_AREA/037","message":"Payload is processed via staging area; check results in Import Monitor","severity":"info","target":"","details":[]}



11. The next step should always be to check the result in the SAP Marketing Cloud system. Therefore you can use the technical apps like  Application Log app, the Import Monitor app or the business user contact related apps e.g. the contact looks like this via Inspect Contact app.


This blog post gave you a good introduction how to use the new SAP Marketing Cloud APIs. We will continue to provide more blog posts referring to those new standard APIs.

Please keep in mind that this blog post was only covering an easy option to get you started.

To get started in productive environments, you should also think about your strategy in terms of:

  • parallel vs. sequential calls to
  • asynchronous vs. synchronous processing of calls
  • package size of one single request depending on the business object
  • error handling & data cleansing on the sender side or receiver side


You want to see more? Check out all of our blogs here.

Your SAP Expert Services – Marketing Practice team.

You must be Logged on to comment or reply to a post.
  • Hello Mark,


    It was a great blog and it is good to see that SAP is releasing their OData API(S) in API API Management using swagger like format. Is SAP planning to deprecate CUAN_IMPORT*** api?


    However, the API is violating REST best principles. We need to have proper CRUD (POST/GET/PUT/PATCH) operation for all entity sets (some of them have only get) and I understand re-implementing Old ABAP Odata services may not be cost effective but I think API’s SAP releasing to outside world shouse use OAS REST design principles and API management should deal with internal complexities of mapping external endpoint to internal OData endpoint.


    Also, The API doesn’t have a mechanism to create/update postal opt in and opt in date . It asks for two keys Marketing Permission ID and Contact ID ( Unlike e-mail and phone we will not have have specific ID) for postal or paper opt in .


    Though CUAN also doesn’t follow OAS rest principles, it atleast provides a mechanism to update marketing permission postal opt in.



  • Hello,


    When you do a GET of contacts, the response is in XML.

    But to do a POST, you need to use JSON…

    Is there a way to harmonize this? e.g. that a GET is also received in JSON?




  • Hi Maik,


    It was very nice blog and easy to simulate using Postman. Just need one more help, how to implement this API in HCI/CPI. We have a requirement to update contact marketing permissions using UUID through CSV file. Please guide the steps to implement this API.




  • Thanks Maik – This is just the article I what I was looking for.  I am able to run the POST through the SAP Netweaver gateway client.  I can see the HTTP/1.1 204 No Content.  I can see my entries in the Import Monitor application and they are showing In Process 

    However, when I try to open up the Fiori app for Inspect Contact or Analyze Contact Origin Data, I get the error “Could not open app. Please try again later”.  I have a Hybris system on AWS provisioned through CAL which we upgraded to 1709.  I copied all of the roles that were in the YMKT_ALL user but many of the tiles do not start the corresponding apps correctly.

    Are there some steps I need to do to get the entries from In Process to Success?






    • Hi Jay,

      please find some information about the staging area here:

      They explain the staging area there: See: “By default, data processing for contacts, interaction contacts, corporate accounts, or marketing permissions is asynchronous. In most cases an OK response, such as a receipt notification, is returned almost immediately. An exception to this would be data uploads that might contain severe errors, such as parse or format errors, and so would not return an OK response but an error message. The data you upload lands in a staging area, where it is then further processed. You can change the default setting to synchronous processing by setting the property Sap-Cuan-ForceSynchronousProcessing to True. In this case, any error messages are returned as soon as they are detected.”

      That’s why the contacts are in process.

      For the inspect contact app I would try different browsers or otherwise it should be an authorization issue.



      • Hi Maik,

        Thanks for your very prompt answer.  We did pass in “Sap-Cuan-ForceSynchronousProcessing: X” and then we were able to see the issues with the data which was helpful.

        We were also able to get the Inspect Contact application to work after adding the permissions and also enabling the underlying OData service.

        Now we are facing the csrf issue since the Hybris system through CAL issues with the certificate.