This tutorial teaches you how to retrieve data in Semarchy xDM using the REST API. You will learn to use simple queries and named queries. This tutorial is based on the Customer B2C demo application, so you will get experience dealing with retrieving fuzzy-matching entities and learning how the REST API works.

What you'll learn

The following tutorial videos assume you have already setup Semarchy xDM and completed the Customer B2C Demo tutorial. If you do not have these two prerequisites, please return to the tutorials main menu to complete the required tutorials so that you can begin with Customer B2C data loaded in your environment.

GO TO TUTORIALS

Enjoy this tutorial!

Before you start

Before following this tutorial, it is advisable to complete the first three tutorials in Integration track: "Configuring Jobs and Loading Data", "Query Data via SQL API", and "Load Data via SQL".

While it is not required, these tutorials give you a stronger foundation to understand the integration concepts you will implement via the REST API. You can find these tutorials from the main menu.

GO TO TUTORIALS

If you have not already done so, you can click on the DOWNLOAD TUTORIAL RESOURCES button to download resources, such as API calls, used within this tutorial.

DOWNLOAD TUTORIAL RESOURCES

The estimated duration of this unit is about 1 hour.

You can watch a video demonstrating the steps you will follow in this tutorial by clicking the "watch video" link below:

Watch video: Retrieve Data via the REST API

In each section of this tutorial, you will find links that take you directly to the part of the video that demonstrates a step you will take. Even though the videos jump to the pertinent section, the video will continue playing to the end. Stop the video after each segment to avoid running to the end of the video.

Knowing how to query data using the REST API is a critical step to building a successful MDM program. While you ordinarily would rely on a middleware tool or a user-designed program to query and load data from xDM, there are business cases where an integration developer needs to connect Semarchy xDM to an external system using the REST API. This allows near real-time queries versus batch loading, which SQL is better suited for.

To understand the underlying methods, you will learn how to query via the REST API in this tutorial unit.

What you'll learn

While it is possible to make calls to the REST API via your web browser, it is better to use a tool specialized for API development environment, especially for this tutorial and the next tutorial, "05. Load Data via the REST API", in this Integration track where you will load data via the REST API.

Therefore, we recommend you use Postman because it is available for free, and it is easy to use. If you prefer to use another tool that your organization supports, you're welcome to do so.

Get Postman app

To begin, download the Postman app for your platform from the Postman website:

GET POSTMAN APP

Once you've downloaded the app, install the Postman App.

Watch video: Get Postman app

Set up credentials

Let's set up your Postman environment, including authentication so you can access Semarchy xDM via the REST API.

Access the REST API is a task normally performed by an integration developer. As a result, we are going to use the semadmin user who has full administrative privileges to do everything in the xDM platform, including using the REST API.

To set up authorization:

  1. Click on the Authorization tab.
  2. Under Type, click the drop-down menu.
  3. Select Basic Auth.

  1. Enter the username and password for your semarchy admin user. You will use the same credentials that you use to connect to xDM as the semadmin user.

    If you followed the Quick Install On-Premises tutorial, then your password is likely semadmin (or whatever you changed the password to when you set up your environment).

If you installed xDM on AWS, then your password is your instance ID. You can find the ID in the AWS EC2 Console.

If you did not perform the Quick Install, please ask your team member who did to provide you with the URL to access xDM.

For more details about the Quick Install, refer to the Quick Install tutorials.

GO TO TUTORIALS


We want to preview the request to test the credentials. To do this, we need a URL with a working REST API request. Below, you will get a template request URL. You will need to modify it to test the request and credentials.

Watch video: Set up credentials

Retrieve all records

You will retrieve all the customer records in the Person entity from the CustomerB2CDemo data location. The template request you need is:

http://<host>:<port>/semarchy/api/rest/query/CustomerB2CDemo/Person/GD

You need to modify the request to use your host and port. If you installed xDM on your local computer following the Quick Install On-Premises tutorial, then you can use the host, localhost, and the port, 8088:

http://localhost:8088/semarchy/api/rest/query/CustomerB2CDemo/Person/GD

If you installed xDM on AWS, you will need your public DNS or IP address. Since the port is 80, you will not need to include it in your request URL. The example from our environment using the public DNS address is:

http://ec2-54-215-241-96.us-west-1.compute.amazonaws.com/semarchy/api/rest/query/CustomerB2CDemo/Person/GD

The corresponding request using the public IP is:

http://54.215.241.96/semarchy/api/rest/query/CustomerB2CDemo/Person/GD

You can use either the public DNS address or the public IP address. We will proceed with the IP address in future examples in this tutorial.

To test your credentials:

  1. Enter the customized request URL (modified for your environment) in the request field.
  2. Check the request is using the GET method.
  3. Click send.
  4. If you have correctly set up the authorization with your credentials, then you should see results returned. These are all the golden customer records returned in JSON format.

Watch video: Retrieve all records

Congratulations

You have successfully learned the background concepts behind how the REST API works in Semarchy xDM. Let's summarize:

In the next step, you will learn how to create a request and how the REST API works.

The ability to retrieve data in xDM is critical to achieving your goals, such as viewing golden data in your BI tools. In this tutorial, we are focused on retrieving customer information via the REST API. This API is useful for external applications to connect to xDM.

For example, if your organization has a call center application that needs to retrieve up-to-date data from Semarchy xDM so that the customer service team has pertinent information while on the phone with a customer, the REST API is the way to integrate these two applications.

What you'll learn

Let's construct your first request.

REST API overview

As a reminder, the REST API is available at the following base URL:

http://<host>:<port>/{war-base-name}/api/rest

Each operation in the REST API is available under this base URL. The URL may also take additional parameters.

The example we will use in this tutorial comes from our xDM environment set up on AWS. The public DNS address is ec2-54-215-241-96.us-west-1.compute.amazonaws.com and the public IP address is 54.215.241.96. This means the base URL is:

http://ec2-54-215-241-96.us-west-1.compute.amazonaws.com/semarchy/api/rest

and

http://54.215.241.96/semarchy/api/rest

In the rest of the tutorial, this URL may be referred to as the [base_url]. The tutorial will also use the public IP address in examples but understand that you can also use the public DNS address.

Construct call to get a record by ID

One common case for searching using customer IDs via the REST API is for pulling up a customer's information at a call center. When customers call in for assistance, such as for a warranty issue or a loyalty program, it is common to ask for the customer's account ID number. The REST API allows your call center system to connect to Semarchy xDM to find the most up-to-date information about the customer.

Use the GET method to retrieve a single customer record.

In our environment, we selected the golden customer record of Mary-Ann Markes to retrieve. This golden record has the ID 11305.

In your environment, the golden ID may differ, depending on in what order Semarchy xDM processed the records. Use the golden ID that you find for the customer record of Mary-Ann Markes.

This is the skeleton of the REST call you will make searching on customer ID:

[base_url]/query/[data_location_name]/[entity_name]/[view type]/[record_ID]

In practice, this is what our request URL looks like in the demo environment we are using:

http://54.215.241.96/semarchy/api/rest/query/CustomerB2CDemo/Person/GD/11305

Be sure to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.

Watch video: Construct call to get record by ID

Retrieve a record in Postman

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

This is the result you can expect:

{
    "ID": 11305,
    "FirstName": "Mary-Ann",
    "LastName": "Markes",
    "PhoneticFirstName": "MRN",
    "PhoneticLastName": "MRKS",
    "NormalizedFirstName": "MARY-ANN",
    "NormalizedLastName": "MARKES",
    "Nickname": "mary-ann",
    "DateOfBirth": "1899-12-31",
    "SourceEmail": "maryann@markes.com",
    "CleansedEmail": "maryann@markes.com",
    "ValidEmailDomain": "1",
    "SourcePhone": "203-967-5612",
    "StandardizedPhone": "(203) 967-5612",
    "PhoneGeocodingData": "Stamford, CT",
    "ValueStatus": "HIGH",
    "PersonType": "CUSTOMER",
    "Address": "1200 Summer St #-103 Stamford CT 06905 US",
    "Address.Street": "1200 Summer St #-103",
    "Address.City": "Stamford",
    "Address.State": "CT",
    "Address.PostalCode": "06905",
    "Address.Country": "US"
}

Note how the information differs from the data you see in the application UI and the SQL query results.

In the next section, you will learn a more advanced request URL to look up a customer record based on first names and no IDs. This involves using a SemQL expression to search through all customer records.

Watch video: Retrieve a record in Postman

Congratulations

In this section, you were introduced to the REST API and how to construct the most basic request.

Let's summarize:

In the next section, you will learn to build on the basic retrieve by retrieving a specific customer's record using the account ID number.

In the previous step, you learned how to retrieve a customer record using the customer's account ID number. It's also common for customers to not have their account ID numbers handy. Customer service representatives will frequently ask the customer for other identifying information, such as the customer's first name and last name or address.

Following this business case, let's build on the previous request URL using the customer's name instead of account number.

What you'll learn

REST API documentation

Before we begin constructing the REST call, let's look at the REST API documentation that Semarchy xDM generates for you automatically. This is a fantastic resource that will help you construct your REST URLs to reduce the risks of mistakes.

You can find the REST API at the URL:

[public_dns_or_ip_address]/semarchy/api/rest/api-ui/index.html

In our environment, the REST documentation URL is: http://54.215.241.96/semarchy/api/rest/api-ui/index.html.

Navigate the documentation by clicking on the drop-down menu in the upper right corner to find the menu. Click on CustomerB2CDemo.

When you scroll down you will find the Person (Customer) section. Find the Query one GD record section within the Person (Customer).

You will find a sample GET request that helps you begin constructing your request URL. This is a good way to start building your REST request.

http://54.215.241.96/semarchy/api/rest/query/CustomerB2CDemo/Person/GD/{record-id}

Watch video: REST API documentation

Retrieve a record by last name

The REST API allows external systems in your organization, such as the call center system, retrieve records in xDM using filters.

You will use the GET method to retrieve a single customer record using a SemQL filter. The SemQL filter works by searching all customer records by the name that the customer provides.

In our environment, we selected the golden customer record of John Edelman to retrieve. Let's retrieve using the last name, Edelman.

This is the skeleton of the REST call you will make using a filter:

[base_url]/query/[data_location_name]/[entity_name]/[view type]?$f=[SemQL_filter]

In practice, this is what our request URL looks like in the demo environment we are using:

http://54.215.241.96/semarchy/api/rest/query/CustomerB2CDemo/Person/GD?$f=LastName%20LIKE%20%27Edelman%27

The SemQL filter originally started as LastName LIKE 'Edelman'.

Remember to substitute the spaces in the URL with %20 and the single quotes with %27. Learn more about percent-encoding (also called URL encoding).

Watch video: Retrieve a record by last name

Retrieve a record with a filter in Postman

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

This is the result you can expect:

{
    "records": [
        {
            "ID": 11303,
            "FirstName": "John",
            "LastName": "Edelman",
            "PhoneticFirstName": "JN",
            "PhoneticLastName": "ETLM",
            "NormalizedFirstName": "JOHN",
            "NormalizedLastName": "EDELMAN",
            "Nickname": "jack",
            "DateOfBirth": "1976-09-03",
            "SourceEmail": "john@jedelman.com",
            "CleansedEmail": "john@jedelman.com",
            "ValidEmailDomain": "1",
            "SourcePhone": "415.381.9176",
            "StandardizedPhone": "(415) 381-9176",
            "PhoneGeocodingData": "Mill Valley, CA",
            "ValueStatus": "NORMAL",
            "PersonType": "CUSTOMER",
            "Address": "591 Redwood Hwy #-1200 Mill Valley CA 94941 US",
            "Address.Street": "591 Redwood Hwy #-1200",
            "Address.City": "Mill Valley",
            "Address.State": "CA",
            "Address.PostalCode": "94941",
            "Address.Country": "US"
        }
    ]
}

Note how the information differs from the data you see in the application UI and the SQL query results.

Watch video: Retrieve a record with a filter in Postman

Congratulations

In this section, you built an advanced request URL using a filter that allowed you to filter on the customer's last name with a SemQL filter instead of account number.

Let's summarize:

In the next section, you will learn about named queries and how to build a custom data structure to create a customized REST endpoint.

In the previous step, you learned how to retrieve a customer record using a SemQL filter that queries the customer's last name.

So far in this tutorial, you have used predefined REST endpoints, such as retrieving a single record and using filters. There will be situations where you need a custom REST endpoint because your systems require a special data structure.

In this section, you will learn how to create a named query in the model design. Then you will use the named query in Postman to retrieve the custom data structure.

What you'll learn

Create the named query

Let's create the named query in the model designer:

  1. Go to the Application Builder. (You will need to log in as a user with Application Design privileges. It is most likely semadmin.)
  2. Open the CustomerB2CDemo model.
  3. Create a new Named Query.

  1. Call the named query PersonByIDWithProducts.

  1. Give the object the name Customer.
  2. Choose the following Object Properties:

  1. Select the PersonProducts object. In the Properties section (found in the bottom panel of the workspace), rename this object to Products.

  1. Expand the Products object properties.
  2. Select the PersonProduct node. Add a new property.

  1. In the object property, set the following:

  1. Select the PersonProduct node again. Add a new property again.
  2. In the object property, set the following:

  1. Select the PersonProduct node again. Add a new property again.
  2. In the object property, set the following:

  1. Save this named query:

  1. For the new Named Query to take effect, you need to refresh the application. You can do this by going to the Customer B2C application. Click the user profile button and click Refresh application.

If you do not want to leave the Application Builder, alternatively you can deploy these model changes in the Management tab for the new named query to take effect. (Right-click the Data Location CustomerB2CDemo.)

  1. You are now ready to use this named query in Postman and see the results of a custom REST endpoint.

Watch video: Create the named query

Call a named query

Let's call the named query to see the results. You will continue to build the named query, adding complexity, in later steps. But it's important to check it works first.

This is the skeleton of the REST call you will make using a named query:

[base_url]/named-query/[data_location_name]/[named_query]/[view type]

In practice, this is what our request looks like in the demo environment we are using:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD

Named query call in Postman

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

The result you should see are all the golden customer records with their corresponding products. Here is an excerpt of what you can expect:

{
    "records": [
        {
            "ID": 11291,
            "CleansedEmail": "saul@rave.com",
            "ValueStatus": "NORMAL",
            "StandardizedPhone": "(484) 375-7261",
            "NormalizedFirstName": "SAUL",
            "PersonType": "CUSTOMER",
            "NormalizedLastName": "RAVE",
            "Products": [
                {
                    "Product": "Carbonite Helmet",
                    "PurchaseDate": "2015-05-20",
                    "RegistrationDate": "2015-06-29"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-04-10",
                    "RegistrationDate": "2016-06-25"
                }
            ]
        },
        {
            "ID": 11292,
            "CleansedEmail": "gail@taulman.com",
            "ValueStatus": null,
            "StandardizedPhone": "969-4377",
            "NormalizedFirstName": "GAIL",
            "PersonType": "PROSPECT",
            "NormalizedLastName": "TAULMAN",
            "Products": [
                {
                    "Product": "Streamliner Saddle",
                    "PurchaseDate": "2015-02-17",
                    "RegistrationDate": "2015-03-05"
                }
            ]
        },
...(continued)
    ]
}

Watch video: Named query call in Postman

Congratulations

Great job creating a named query. You can see how named queries can be useful for creating custom data structures to support your organization's precise business needs when integration Semarchy xDM with different systems. Let's summarize:

In the next section, you will build on the basic named query you created by adding query parameters that allow you to filter results, similar to the section #4 above Get a customer record by last name where you use a SemQL filter.

In the previous section, you learned how to create a basic named query. This created a custom REST endpoint that allows you to retrieve a customer record with that customers' corresponding products.

In this section, you will build upon the named query by adding in advanced features. You will add query parameters that allow you to filter the results with a SemQL expression, similar to the filter you used in the Get a customer record by last name section #4 where you filtered on the customer's last name.

What you'll learn

Add query parameters

In our business case of a customer support call center, the customer service representative wants to pull up information about the customer in the call center system. Usually, the representative will ask for the customer's information, such as an email address or account ID number, which both can serve as identifiers.

The REST endpoint must have a way to submit this identifier information to xDM. The way we achieve this is by using query parameters.

Let's create a query parameter in the named query:

  1. Go to the Application Builder.
  2. Open the PersonByIDWithProducts named query you created in the previous section.
  3. Add a new query parameter.

  1. In the query parameter, set the following:

You do not need to put any default values. Leave those fields blank. These query parameters are not mandatory. Leave the Mandatory checkbox unchecked.

  1. Remember to save your named query. You need to refresh the application (alternatively, you can also deploy the model if you don't want to move to the front-end application due to convenience) for the query parameter to take effect.

Watch video: Add query parameters

Test the named query

Run the same named query that you used in the previous section in Postman:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

When you run exactly the same request as before, you will now get the same results as the previous step:

{
    "records": [
        {
            "ID": 11291,
            "CleansedEmail": "saul@rave.com",
            "ValueStatus": "NORMAL",
            "StandardizedPhone": "(484) 375-7261",
            "NormalizedFirstName": "SAUL",
            "PersonType": "CUSTOMER",
            "NormalizedLastName": "RAVE",
            "Products": [
                {
                    "Product": "Carbonite Helmet",
                    "PurchaseDate": "2015-05-20",
                    "RegistrationDate": "2015-06-29"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-04-10",
                    "RegistrationDate": "2016-06-25"
                }
            ]
        },
...(continued)
    ]
}

This check is important because it confirms that you did not break your named query after adding the query parameters.

Watch video: Test the named query

Use the query parameters

Adding query parameters is the first step required to filter the records xDM retrieves. The second step requires that you set up a filter to that uses these query parameters. The filter is a SemQL expression that compares the incoming information with the existing data in xDM.

Let's create the filter and see how it works with query parameters.

  1. You will need to add a filter to use the query parameters. Scroll to the top of the named query configuration in the Application Builder. Find the Filter field:

  1. Open the SemQL editor. Define this filter (copy and paste it):
SEM_NUMBER_TO_CHAR( ID ) = :QUERY_PARAM_IDENTIFIER
OR CleansedEmail = :QUERY_PARAM_IDENTIFIER
OR REGEXP_REPLACE( StandardizedPhone, '[^[:digit:]]', '', 'g' ) = REGEXP_REPLACE( :QUERY_PARAM_IDENTIFIER, '[^[:digit:]]', '', 'g' )

  1. Save and refresh the application.

Watch video: Use the query parameters

Call updated named query

To use the named query, include the parameters in the request URL. In this part, you will learn how to update your request URL to include the query parameters and corresponding values (the arguments).

These are the 3 identifiers that this named query can accept:

  1. Customer's account ID number
  2. Email address
  3. Phone number

The query parameter IDENTIFIER is set up to only accept strings. However, the filter is able to check for account IDs, email addresses, and phone numbers. It handles the account ID by casting a number into a string on the fly for comparing to the xDM ID. It takes a phone number and strips out non-digit characters to compare to the phone number in xDM.

This is the skeleton of the REST call you will make using a named query:

[base_url]/named-query/[data_location_name]/[named_query]/[view type]?IDENTIFIER=[customer_ID_or_cleansed_email_or_phone_number]

After the IDENTIFIER query parameter, you can provide the customer's account ID number, email address, or phone number.

Here are examples of how to construct the request URL, using the public IP address from our demo environment.

Imagine the customer Toni Mattos calls into the customer support number with a warranty issue. The customer support representative asks Toni for her account number to pull up her information. She supplies her account number (in other words, golden record ID), 11299. This is an example of the request that the call center system can make to retrieve Toni's record from xDM.

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=11299

Alternatively, if Toni forgot her account ID number, then the support representative can ask for her email address, toni@mattos.com. This is the request that the call center system can use to retrieve Toni's information:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=toni%40mattos.com

Similarly, if Toni forgot her account ID number and the email she provided is not matching with anything in the system, then the support representative can ask for her phone number, (321) 727-6512. This is the request that the call center system can use to retrieve Toni's information:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=3217276512

Watch video: Call updated named query

Named query call in Postman

Retrieve record with customer's account ID

First, start with the customer's account number (golden record ID).

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=11299

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

The result you should see is Toni Mattos' information and the corresponding products she has purchased and registered. Here is the result that you can expect:

{
    "records": [
        {
            "ID": 11299,
            "CleansedEmail": "toni@mattos.com",
            "ValueStatus": "HIGH",
            "StandardizedPhone": "(321) 727-6512",
            "NormalizedFirstName": "TONI",
            "PersonType": "CUSTOMER",
            "NormalizedLastName": "MATTOS",
            "PersonProducts": [
                {
                    "Product": "Carbonite Century ",
                    "PurchaseDate": "2016-07-15",
                    "RegistrationDate": "2016-08-04"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2014-09-17",
                    "RegistrationDate": "2014-11-26"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-08-20",
                    "RegistrationDate": "2016-10-08"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-10-09",
                    "RegistrationDate": "2016-10-29"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2015-06-16",
                    "RegistrationDate": "2015-07-23"
                },
                {
                    "Product": "Streamliner Saddle",
                    "PurchaseDate": "2015-03-24",
                    "RegistrationDate": "2015-05-10"
                }
            ]
        }
    ]
}

Notice that the attributes related to the person are not in a user-friendly order. In the next step, you will reorder the attributes so that the first name and last name attributes come after the ID.

Watch video: Named query call in Postman

Reorder attributes in the named query

Let's reorder attributes so that they are in a logical order:

  1. Go to the named query PersonByIDWithProducts in the Application Builder.
  2. Use the Move Up and Move Down arrows to rearrange the object properties to be in the following order:

  1. Refresh the application so that the new properties order takes effect.

Watch video: Reorder attributes

Retrieve record with customer's email

In case the customer doesn't have her account number, let's see what it would look like to retrieve her customer account information based on her email:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=toni%40mattos.com

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

The result you should see is Toni Mattos' information and the corresponding products she has purchased and registered. Here is an excerpt of what you can expect:

{
    "records": [
        {
            "ID": 11299,
            "NormalizedFirstName": "TONI",
            "NormalizedLastName": "MATTOS",
            "StandardizedPhone": "(321) 727-6512",
            "CleansedEmail": "toni@mattos.com",
            "PersonType": "CUSTOMER",
            "ValueStatus": "HIGH",
            "Products": [
                {
                    "Product": "Carbonite Century ",
                    "PurchaseDate": "2016-07-15",
                    "RegistrationDate": "2016-08-04"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2014-09-17",
                    "RegistrationDate": "2014-11-26"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-08-20",
                    "RegistrationDate": "2016-10-08"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-10-09",
                    "RegistrationDate": "2016-10-29"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2015-06-16",
                    "RegistrationDate": "2015-07-23"
                },
                {
                    "Product": "Streamliner Saddle",
                    "PurchaseDate": "2015-03-24",
                    "RegistrationDate": "2015-05-10"
                }
            ]
        }
    ]
}

Watch video: Customer's email

Retrieve record with customer's phone number

In case the customer doesn't have her account number or email, let's see what it would look like to retrieve her customer account information based on her phone number:

http://54.215.241.96/semarchy/api/rest/named-query/CustomerB2CDemo/PersonByIDWithProducts/GD?IDENTIFIER=3217276512

To run this request in Postman:

  1. Enter your request URL into the request field. Remember to substitute your public IP address or public DNS address instead of using our server's information, 54.215.241.96.
  2. Double check the method is GET.
  3. Click Send.
  4. See the results returned in JSON format.

The result you should see is Toni Mattos' information and the corresponding products she has purchased and registered. Here is an excerpt of what you can expect:

{
    "records": [
        {
            "ID": 11299,
            "NormalizedFirstName": "TONI",
            "NormalizedLastName": "MATTOS",
            "StandardizedPhone": "(321) 727-6512",
            "CleansedEmail": "toni@mattos.com",
            "PersonType": "CUSTOMER",
            "ValueStatus": "HIGH",
            "Products": [
                {
                    "Product": "Carbonite Century ",
                    "PurchaseDate": "2016-07-15",
                    "RegistrationDate": "2016-08-04"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2014-09-17",
                    "RegistrationDate": "2014-11-26"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-08-20",
                    "RegistrationDate": "2016-10-08"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2016-10-09",
                    "RegistrationDate": "2016-10-29"
                },
                {
                    "Product": "Renaud Martin Skin Suit",
                    "PurchaseDate": "2015-06-16",
                    "RegistrationDate": "2015-07-23"
                },
                {
                    "Product": "Streamliner Saddle",
                    "PurchaseDate": "2015-03-24",
                    "RegistrationDate": "2015-05-10"
                }
            ]
        }
    ]
}

Watch video: Customer's phone number

Congratulations

You learned how to retrieve data in xDM using the REST API. Let's summarize:

Great job going through this tutorial!

You will find more information about Integration jobs, such as how to query and load data using SQL in this Integration track.

Well done! You have run your first REST GET requests to retrieve data from Semarchy xDM.

In this tutorial, you learned:

You will find more Integration information, including how to load data using SQL and how to use the REST API in the Integration tutorial series.

There are also tutorials about how to design applications in the Data Authoring and Data Consolidation tutorial tracks.

Go back to the main menu to see more tutorials.

GO TO TUTORIALS

Go further with xDM

This tutorial taught you how to load data into xDM using SQL. xDM is capable of addressing all types of data, including customer data, location data, reference data, organization data, supplier data, and other domains.

Visit our website to learn about the different solutions we provide.