This article teaches you how to run your first REST API request to load data into Semarchy xDM. If you would like a more detailed hands-on experience, follow the Load Data via the REST API tutorial.


1. In order to load data for a basic entity, download the Postman application from the Postman website. Please follow the instructions to set up a request and authentication.

2. Open Postman and click the New button in the toolbar.

3. Select Request.

4. Enter a Name for your request. Optionally, select Create Collection and enter a name for the collection which essentially serves as a virtual folder to store your request. Click Save.

5. Next, we will configure our authentication. There are two authentication methods supported in Semarchy.

  • Basic authentication: where you provide an Authorization HTTP header containing username: password encoded in base64.
  • API Key authentication, where you provide an API-Key HTTP header containing an API key created in Semarchy Configuration.

For this example, we will follow the steps using API authentication

a. Select on the Authorization tab.

b. Under Type, open the drop-down menu.

c. Select API Key.

d. To generate an API Key, please refer to this  community discussion.


6. Retrieve the request URL for your environment from the REST API Documentation:

a. Navigate to the Semarchy xDM application and select REST API on the Welcome page.

b. Select Getting Started > CustomerB2CDemo (or select another application if you want to test with another one) and navigate to your data location.

c. On the left navigation menu, select Create a load then copy the URL in the clipboard. For example, see the screenshot below.

7. Go back to Postman, change the method type to POST and enter the request URL (modified for your environment) in the Request field.

The POST request is an “HTTP” method that sends data through a request body to a web server. When sending a POST request, the general intent is to make some changes to the server, such as updates, deletions, or additions.

8. Navigate to the Body tab to configure the payload.

a. Select Raw and then select the format type to JSON.

b. If you are using the CustomerB2CDemo application for your test, copy and paste the following sample request from our Integration Guide. Otherwise you can adapt it for the application you are using.

{
  ""action"":""PERSIST_DATA"",
  ""persistOptions"": {
  ""defaultPublisherId"": ""CRM"",
  ""optionsPerEntity"": {
  ""Customer"": {
  ""enrichers"":[],
  ""validations"":[],
  ""queryPotentialMatches"": true
  }
  },
  ""missingIdBehavior"": ""GENERATE"",
  ""persistMode"": ""IF_NO_ERROR_OR_MATCH""
  },
  ""persistRecords"": {
  ""Customer"": [
  {
  ""CustomerName"": ""Gadgetron""
  }
  ]
  }
 }

c. Click Send to send the request.


9. If you have entered the correct credentials and submit the load with no formatting errors in the body, you will receive a message indicating that the data was persisted.

10. Now that the load has persisted, we can verify that a new batch has triggered by navigating to the Application Builder > Management > Latest Integration Batches.

"