1. REST API for Oracle CX Sales and B2B ServiceREST API for Sales and Fusion Service in Oracle Fusion Cloud Customer Experience
  2. Use Cases
  3. Identify Duplicate Organizations and Persons

Identify Duplicate Organizations and Persons

A subscription to Fusion Data Quality lets you enable interactive duplicate identification in Customer Data Management to avoid the creation of new customer records that may be duplicates of existing records in the customer registry. With this feature, when you attempt to save a new customer record, the application notifies you of the existence of potential duplicate records and lets you choose between continuing to create a new record versus using an already existing record. The Fusion Data Quality service also supports interactive duplicate identification using REST APIs if you want to develop a similar duplicate identification flow for a custom client, such as a mobile application or Oracle Visual Builder web interface for creating customer records. This section helps you understand the REST APIs' capabilities, implementation, and usage.

Prerequisites

The Fusion Data Quality Duplicate Identification REST functions require a subscription to any Oracle CX Sales service base along with the Oracle Fusion Data Quality service option. Once the necessary subscriptions are active, the implementation must configure and activate data quality matching configurations for Organizations and Persons using the Manage Enterprise Data Quality Matching Configuration setup task. For more information on this task, refer to the "Implementing Customer Data Management for CX Sales and Fusion Service" implementation guide on the CX Sales Help Center.

Overview of REST Data Quality Matching

REST-based duplicate identification is available for Organizations and Persons objects and is provided through specialized actions of their standard CX Sales REST resources. For more information about the CX Sales Organization and Person REST resources, you can refer to the "REST API for CX Sales and Fusion Service" guide on the CX Sales Help Center.

Example URL

Use this resource URL format.

POST

crmRestAPI/resouces/11.13.18.05/<hubOrganizations|hubPersons>/

The following sections provide details for the Organization and Persons duplicate identification APIs and their specialized sub-resources.

Identify Duplicate Organizations

REST-based duplicate identification for Organization is provided through a specialized action for the CX Sales REST API for Organizations called 'findDuplicates'.

Example URL

USe this URL format.

POST

crmRestAPI/resouces/11.13.18.05/hubOrganizations/action/findDuplicates

The body of the request must contain a flat map structure of type "hubOrganization" having one or more attribute names and match values, with the attribute names conforming to the top-level schema of the Organization REST object. The "attribute name: match value" map may include service-enabled custom attributes created with Application Composer.

The matching behavior of the API is governed by the Real Time Match Configuration Parameters settings per the active data-quality-matching configuration for the Organization object. These settings control:
  • The match threshold score
  • The cluster key mode
  • Whether standard or custom scoring rules are used

The body of the response consists of a list of Organization records from the CX Sales customer registry that satisfy the match criteria per the configured match settings and the match attribute/value pairs submitted in the request. Each element of the list is a flat map structure that provides the identifiers for the Organization, some commonly used attribute values, and the scoring rule and attribute values that drove the match score.

The hubOrganization response schema is as follows:
  • PartyId
  • PartyNumber
  • OrganizationName
  • FormattedAddress
  • FormattedPhoneNumber
  • RawPhoneNumber
  • Url
  • EmailAddress
  • PrimaryContactPartyId
  • PrimaryContactPartyNumber
  • CreationDate
  • LastUpdateDate
  • LastUpdatedBy
  • CreatedBy
  • MatchScore
  • MatchRule
  • MatchedAttributes

Examples

Example 1: Successful Request with Possible Duplicates

Example of Request Body

Here is an example of the request body in JSON format.

{
"hubOrganization":
 {
 "OrganizationName": "Merrrill Technologies",
 "AddressLine1": "500 South Drive",
 "PostalCode": "94035",	
 "State": "CA",
 "Country":"US"
 }
}

Example of Response Body

Here's an example of the response body in JSON format.

{ 
"result": 
 [ 
 {
 "PartyId":"300100193515606",   
 "PartyNumber": "CDRM_970814",  
 "OrganizationName": "Merrill Technologies", 
 "FormattedAddress": "500 South Drive,MOFFETT FIELD, CA 94035", 
 "FormattedPhoneNumber": null,    
 "RawPhoneNumber": null,  
 "Url": null,    
 "EmailAddress": null, 
 "PrimaryContactPartyId":null,   
 "PrimaryContactPartyNumber": null,   
 "PrimaryContactPartyName":null,      
 "CreationDate":"2019-09-23 07:57:37.263",   
 "LastUpdateDate": "2019-09-23 08:01:11.364", 
 "LastUpdatedBy": "SALES_ADMIN",   
 "CreatedBy": "SALES_ADMIN",
 "MatchScore": "77",    
 "MatchRule": "[E125C] Full name all words shorter with typos; premise; no subpremise; postal code starts with",   
 "MatchedAttributes": "PostalCode,AddressLine1,Country,OrganizationName"  
 }  
 ] 
}

Example 2: Successful Request with no Possible Duplicates Identified

Example of Request Body

Here is an example of the request body in JSON format.

{
 "hubOrganization": 
 {
 "OrganizationName": "Merrrill Technologies"
 }
}

Example of Response Body

Here is an example of the response body in JSON format.

{
  "result": []
}

Example 3: Successful Request with a Custom Attribute in the Request Body

Example of Request Body

Here is an example of the request body in JSON format.

{
  "hubOrganization": 
   { 
   "OrganizationName": "Merrill Technologies",
   "OrganizationDEO_NonVerifiedVAT_c": "A5678" 
   }
 }

Example of Response Body

Here's an example of the response body in JSON format.

{ 
 "result": 
 [  
 { 
  "PartyId": "300100180759704", 
  "PartyNumber": "CDRM_859821",  
  "OrganizationName": "Merrill Technologies", 
  "FormattedAddress": "500 South Drive,MOFFETT FIELD, CA 94035",
  "FormattedPhoneNumber": null,    

"RawPhoneNumber": null, 
  "Url": null,     
  "EmailAddress": null,   
  "PrimaryContactPartyId": null,   
  "PrimaryContactPartyNumber": null,  
  "PrimaryContactPartyName": null,
  "CreationDate": "2019-09-26 21:54:26.208", 
  "LastUpdateDate": "2019-10-01 05:32:56.461",    
  "LastUpdatedBy": "SALES_ADMIN",   
  "CreatedBy": "swatson",    
  "MatchScore": "89", 
  "MatchRule": "[E020H] Full name exact; VAT number", 
  "MatchedAttributes": "OrganizationDEO_NonVerifiedVAT_c,OrganizationName"   
 }  
 ] 
 }

Identify Duplicate Persons

REST-based duplicate identification for Persons is provided through a specialized action for the CX Sales REST API for Persons called 'findDuplicates'.

Example URL

Use this resource URL format.

POST

crmRestAPI/resouces/11.13.18.05/hubPersons/action/findDuplicates

The body of the request must contain a flat map structure of type "hubPerson" having one or more attribute names and match values, with the attribute names conforming to the top-level schema of the hubPersons REST object. The "attribute name: match value" map may include service-enabled custom attributes created with Application Composer.

The matching behavior of the API is governed by the Real Time Match Configuration Parameters settings per the active data-quality-matching configuration for the Contact object. These settings control:

  • The match threshold score
  • The cluster key mode
  • Whether standard or custom scoring rules are used

The body of the response consists of a list of Persons records from CX Sales customer registry that satisfy the match criteria per the configured match settings and the match attribute/value pairs submitted in the request. Each element of the list is a flat map structure that provides the identifiers for the Persons, some commonly used attribute values for Persons, and the scoring rule that drove the match score. The contact response schema is as follows:

  • PartyId
  • PartyNumber
  • FirstName
  • LastName
  • MiddleName
  • FormattedAddress
  • RawHomePhoneNumber
  • FormattedHomePhoneNumber
  • RawWorkPhoneNumber
  • FormattedWorkPhoneNumber
  • RawMobileNumber
  • FormattedMobileNumber
  • EmailAddress
  • OrganizationPartyId
  • OrganizationPartyNumber
  • OrganizationPartyName
  • LastUpdateDate
  • LastUpdatedBy
  • CreatedBy
  • CreationDate
  • MatchScore
  • MatchRule
  • MatchedAttributes

Examples

Example 1: Successful Request with Possible Duplicates

Example of Request Body

Here is an example of the request body in JSON format.

{
  "hubPerson":  
  {  
 "FirstName":"Arnold",  
 "LastName": "Smith"
 "EmailAddress": "Arnold.smith@email.abc",
 "Address1":"318 Elm St",
 "PostalCode": "53421" 
  }  
}

Example of Response Body

Here's an example of the response body in JSON format.

{
    "result": [
        {
            "PartyId": "300100544978841",
            "PartyNumber": "CDRM_935497",
            "FirstName": "Arnold",
            "LastName": "Smith",
            "MiddleName": null,
            "FormattedAddress": "319 Elm St,Anytown,53421",
            "RawHomePhoneNumber": null,
            "FormattedHomePhoneNumber": null,
            "RawWorkPhoneNumber": null,
            "FormattedWorkPhoneNumber": null,
            "RawMobileNumber": null,
            "FormattedMobileNumber": null,
            "EmailAddress": "Arnold.smith@email.abc",
            "OrganizationPartyId": null,
            "OrganizationPartyNumber": null,
            "OrganizationPartyName": null,
            "LastUpdateDate": "2021-02-25 19:35:23.52",
            "LastUpdatedBy": "SALES_ADMIN",
            "CreatedBy": "SALES_ADMIN",
            "CreationDate": "2021-02-25 19:35:18.003",
            "MatchScore": "100",
            "MatchRule": "[I020B] Name exact; address; e-mail",
            "MatchedAttributes": "FirstName,LastName,Address1,EmailAddress"
        }]}

Tips and Considerations

  • The "findDuplicates" action returns duplicate candidates of the same record types supported by the base hubOrganizations and hubPersons REST resources.
  • The list of matching organizations or persons returned by the "findDuplicates" action is sorted in descending match score order.
  • The maximum number of match candidates included in the response has a default recommended value of 20, but can be configured with the ORA_ZCQ_MAX_CANDIDATES profile option.
  • The hubOrganization and hubPerson "findDuplicates" actions do not require additional roles or privileges beyond those needed to access the base hubOrganizations and hubPersons REST resource endpoints.
  • The "findDuplicates" request body may only contain attributes from the top-level hubOrganization or hubPerson resource schema. Match attributes for child collections are currently not supported.
  • The "findDuplicates" actions are designed to help custom clients replicate the interactive duplicate identification flow provided by Customer Data Management’s Party Center interface.
  • The "findDuplicates" functionality is part of the Oracle CX customer mastering and can work with predictable data shapes containing enough information to satisfy candidate identification and scoring processes. It is not intended to be a generic search interface for customer records.
  • The "findDuplicates" response returns an HTTP Response Status code of 200 for successful requests:
    • The service will ignore incorrectly named match attributes as long as there is at least one correct attribute mapping in the request body
    • A successful response can have zero or more matches
  • The response contains an HTTP Response Status code of 400 for most error conditions listed below:
    • The request body contains no correctly named match attributes
      • "The data quality service encountered an error when identifying matches"
  • The structure of request is invalid, such as missing a required quote, comma, or brace
    • "Unable to parse the provided payload"
  • The Data Quality Matching service is not enabled or has no active configuration
    • "Cleansing operations couldn't be performed because the data quality match server is disabled. Contact your help desk."
  • Refer to the hubOrganization or hubPerson REST endpoint ‘describe’ response to identify the correct names for service-enabled custom attributes
    • Do not use the custom attribute name prefix pattern with standard attributes
    • The 'describe' for the hubPersons object can be read from "https://<server>>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/hubPersons/describe"
    • The 'describe' for the hubOrganization object can be read from "https://<server>>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/hubOrganizations/describe"