Skip to Content


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 Hybris 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 Hybris 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 Hybris Marketing Cloud

In general the communication management setup in SAP Hybris 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 Hybris Marketing Cloud

After setting up the communication management on SAP Hybris 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 Hybris 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 Hybris 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 Hybris 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 Hybris 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 Hybris Marketing Cloud system.

Step 3: Writing Contact Data to SAP Hybris Marketing Cloud

For the posting of contact origin data we have to do first a GET call to the Hybris 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 Hybris 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 Hybris 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 Hybris 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 Hybris 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 Hybris Marketing 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 Hybris 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 Hybris Expert Services – Marketing Practice team.

To report this post you need to login first.


You must be Logged on to comment or reply to a post.

  1. Sravya Talanki

    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.



  2. Joyca Vervinckt



    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?





Leave a Reply