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 Accounts and Contacts

Identify Duplicate Accounts and Contacts

A subscription to Fusion Data Quality lets you enable interactive duplicate identification in Customer Center 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 Accounts and Contacts 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 both Account and Contact objects and is provided through specialized actions of the standard CX Sales REST resources for Accounts and Contacts. For more information about the CX Sales Account and Contact 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/<contacts|accounts>/action/findDuplicates

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

Identify Duplicate Accounts

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

Example URL

Use this resource URL format.

POST

crmRestAPI/resouces/11.13.18.05/accounts/action/findDuplicates

The body of the request must contain a flat map structure of type "account" having one or more attribute names and match values, with the attribute names conforming to the top-level schema of the Account 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 Account 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 account 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 account, some commonly used attribute values for accounts, the primary contact, the account owner, and the scoring rule that drove the match score. The account response schema is as follows:

  • CreatedBy
  • CreationDate
  • FormattedAddress
  • FormattedPhoneNumber
  • EmailAddress
  • LastUpdateDate
  • LastUpdatedBy
  • MatchedAttributes
  • MatchRule
  • MatchScore
  • OrganizationName
  • OwnerEmailAddress
  • OwnerName
  • OwnerPartyId
  • OwnerPartyNumber
  • PartyId
  • PartyNumber
  • PrimaryContactPartyId
  • PrimaryContactPartyName
  • PrimaryContactPartyNumber
  • RawPhoneNumber
  • Url

Examples

Example 1: Successful Request with Possible Duplicates

Example Request

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


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

Example Response

Here is 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,      
 "OwnerPartyId": "100010025532672",   
 "OwnerName":"Gabrielle Lee",    
 "OwnerPartyNumber": "100010025532672", 
 "OwnerEmailAddress": "asomebody@office.com",  
 "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 Request

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


{
 "account": 
 {
 "OrganizationName": "Merrrill Technologies"
 }
}

Example Response

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 Request

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


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

Example Response

Here is 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,   
  "OwnerPartyId": "300100181193090",  
  "OwnerName": "Shane Watson",  
  "OwnerPartyNumber": "CDRM_859820",   
  "OwnerEmailAddress": "asomebody@office.com",    
  "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 Contacts

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

Example URL

Use this resource URL format.

POST

crmRestAPI/resouces/11.13.18.05/contacts/action/findDuplicates

The body of the request must contain a flat map structure of type "contact" having one or more attribute names and match values, with the attribute names conforming to the top-level schema of the Contact 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 contact 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 contact, some commonly used attribute values for contacts, the contact's primary account, the contact owner, and the scoring rule that drove the match score. The contact response schema is as follows:

  • AccountName

  • AccountPartyId

  • AccountPartyNumber

  • CreatedBy

  • CreationDate

  • EmailAddress

  • FirstName

  • FormattedAddress

  • FormattedHomePhoneNumber

  • FormattedMobileNumber

  • FormattedWorkPhoneNumber

  • LastName

  • LastUpdateDate

  • LastUpdatedBy

  • MatchedAttributes

  • MatchRule

  • MatchScore

  • MiddleName

  • OwnerEmailAddress

  • OwnerPartyId

  • OwnerPartyName

  • OwnerPartyNumber

  • PartyId

  • PartyNumber

  • RawHomePhoneNumber

  • RawMobileNumber

  • RawWorkPhoneNumber

Examples

Example 1: Successful Request with Possible Duplicates

Example Request

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

 
{
  "contact":  
  {  
 "FirstName":"Arnold",  
 "LastName": "Smith"  
  }  
}

Example Response

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


 { 
 "result": 
 [ 
 { 
 "PartyId": "300100198851877", 
 "PartyNumber": "CDRM_859893", 
 "FirstName": "Arnold",  
 "LastName": "Smith", 
 "MiddleName": null,  
 "FormattedAddress": null, 
 "RawHomePhoneNumber": null,
 "FormattedHomePhoneNumber": null, 
 "RawWorkPhoneNumber": null, 
 "FormattedWorkPhoneNumber": null, 
 "RawMobileNumber": null,  
 "FormattedMobileNumber": null, 
 "EmailAddress": null, 
 "AccountPartyId": "300100180759704", 
 "AccountPartyNumber": "CDRM_859821", 
 "AccountName": "Merrill Technologies", 
 "OwnerPartyId": "100010025532672",
 "OwnerPartyName": "Gabrielle Lee",  
 "OwnerPartyNumber": "100010025532672",
 "OwnerEmailAddress": "asomebody@office.com" 
 "LastUpdateDate": "2019-10-01 16:24:45.407", 
 "LastUpdatedBy": "SALES_ADMIN", 
 "CreatedBy": "SALES_ADMIN", 
 "CreationDate": "2019-10-01 16:20:14.023", 
 "MatchScore": "65",  "MatchRule": "[I020U] Name exact; no address",  
 "MatchedAttributes": "FirstName,LastName"  
 },
 { 
 "PartyId": "300100198842148", 
 "PartyNumber": "CDRM_859892", 
 "FirstName": "Arnold", 
 "LastName": "Smith",
 "MiddleName": null, 
 "FormattedAddress": "400 Oracle Parkway,Redwood Shores, CA 94065", 
 "RawHomePhoneNumber": null, 
 "FormattedHomePhoneNumber": null, 
 "RawWorkPhoneNumber": null,
 "FormattedWorkPhoneNumber": null, 
 "RawMobileNumber": null, 
 "FormattedMobileNumber": null, 
 "EmailAddress": null,
 "AccountPartyId": null, 
 "AccountPartyNumber": null, 
 "AccountName": null, 
 "OwnerPartyId": "100010025532174", 
 "OwnerPartyName": "Gabrielle Lee", 
 "OwnerPartyNumber": "100010025532174",
 "OwnerEmailAddress": "asomebody@office.com", 
 "LastUpdateDate": "2019-10-01 16:14:13.193", 
 "LastUpdatedBy": "SALES_ADMIN", 
 "CreatedBy": "SALES_ADMIN", 
 "CreationDate": "2019-10-01 16:13:01.036", 
 "MatchScore": "65",
 "MatchRule": "[I020U] Name exact; no address",
 "MatchedAttributes": "FirstName,LastName" 
 }
 ]
 }

Example 2: Successful Request Using accountPartyNumber to Constrain Contact Match Results to Contacts of a Specific Account

Example Request

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


{
 "contact":
 {  
 "FirstName": "Arnold",  
 "LastName": "Smith"  
 },  
 "accountPartyNumber": "CDRM_859821" 
} 

Example Response

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


{
 "result":  
 [  
 {   
 "PartyId": "300100198851877",   
 "PartyNumber": "CDRM_859893",  
 "FirstName": "Arnold",      
 "LastName": "Smith",  
 "MiddleName": null,     
 "FormattedAddress": null,   
 "RawHomePhoneNumber": null,   
 "FormattedHomePhoneNumber": null, 
 "RawWorkPhoneNumber": null,    
 "FormattedWorkPhoneNumber": null,   
 "RawMobileNumber": null,     
 "FormattedMobileNumber": null,   
 "EmailAddress": null,       
 "AccountPartyId": "300100180759704", 
 "AccountPartyNumber": "CDRM_859821",   
 "AccountName": "Merrill Technologies",  
 "OwnerPartyId": "100010025532672",   
 "OwnerPartyName": "Gabrielle   Lee",
 "OwnerPartyNumber": "100010025532672", 
 "OwnerEmailAddress": "asomebody@office.com",
 "LastUpdateDate": "2019-10-01 16:24:45.407", 
 "LastUpdatedBy": "SALES_ADMIN",   
 "CreatedBy": "SALES_ADMIN",     
 "CreationDate": "2019-10-01 16:20:14.023",   
 "MatchScore": "65",    
 "MatchRule": "[I020U] Name exact; no address",  
 "MatchedAttributes": "FirstName,LastName"    
 }   
 ]
}

Tips and Considerations

  • The "findDuplicates" action returns duplicate candidates of the same record types supported by the base Account and Contact REST resources:
    • Person candidates that are Contacts
    • Organization candidates that are Sales Accounts or Sales Prospects
  • The list of matching accounts or contacts 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 Account and Contact "findDuplicates" actions do not require additional roles or privileges beyond those needed to access the base Account and Contact REST resource endpoints.
  • The "findDuplicates" request body may only contain attributes from the top-level Account or Contact 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 CX Sales' Customer 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 Account or Contact 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 Contact object can be read from "https://<server>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/contacts/describe"
    • The 'describe' for the Account object can be read from "https://<server>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/accounts/describe"