📘

About this guide

This guide teaches you how to control the Demyst entity resolution capability in an Data API call. This will empower you to make inferences on which records correspond to the same entity.

Steps

1 - Create a new Data API

Navigate to https://demyst.com/app/create-api and include the Connector that you want to include in your new Data API.

2 - Configure key-value pairs for entity resolution

The match_key_conditions option is available for hosted Connectors (Connector IDs beginning with 'hosted') to specify the matching criteria from the inputs. This is helpful when the accuracy of your inputs is uncertain. For example, there may be a business that has changed locations but you only know their city and state. You can filter your matches to only return results with matching city and state.

If match_key_conditions is provided, during entity resolution we will only make queries that use the key groupings in the specified match key conditions. Without this specification, we will make all possible entity resolution queries.

Add your low code JSON snippet to the configuration section of the Data API.

#The match key is business_name, city, and state only as the post_code and street could be inaccurate
  since the business office may have moved recently.
{
  "providers": {
    "hosted_experian_cpdb": {
      "version": "$latest"
    }
  },
  "config": {
    "match_key_conditions": ["business_name, city, state"]
  }
}

That configuration can be saved in the Data API directly.

👍

Your API is now configured.

3 - Test your new Data API

Test your new Data API with the sandbox interface or programmatically.

Additional Details

Syntax

The value associated with the match_key_conditions key is a JSON array. This array can include the string of comma-separated attributes as seen in the above example, or their equivalent 2-character encoding. Multiple conditions should be formatted as comma-separated strings. like below.

{
  ...
  "config": {
    "match_key_conditions": [
      "business_name, city, state",
      "phone"
    ]
  }
}

Below are a set of possible values that a match_key_conditions array may contain.

2-character encoding, comma-separated string of attributes

"00", "ssn"
"01", "first_name, last_name, dob, whole_address"
"02", "first_name, last_name, dob, post_code"
"03", "first_name, last_name, whole_address"
"04", "first_name, last_name, post_code"
"05", "first_name, last_name, city, state"
"06", "last_name, post_code, dob"
"07", "whole_address, dob"
"08", "first_name, email_address"
"09", "first_name, phone"
"10", "last_name, email_address"
"11", "business_name, whole_address"
"12", "business_name, post_code"
"13", "business_name, city, state"
"14", "phone"
"15", "ein"
"16", "domain"

As you can see from the 2-character encoding
match_key_conditions: ["04", "07"]
AND
match_key_conditions: ["first_name, last_name, post_code", "whole_address, dob"]
are exactly the same! Use whichever best suits you.

Spotting matched keys in a Data API response

Whether or not match_key_conditions are provided as input qualifiers, hosted connectors will specify upon which attribute matching occurred through an output key named match_keys. Match keys might be Demyst Types, or attributes specific to the connector.

If we matched on a person’s nickname or a business name alias, rather than the literal queried value for that field (i.e. first_name or business_name), we will output "common_nickname" or "business_name_aka" in the match_keys string instead of "first_name" or "business_name". This will apply to cases where an input “first_name” was Tom instead of Thomas, and so on.

Look for something like the following in your Demyst Data API responses to find what keys we matched on from your inputs.

{
    "transaction_id": "123abc-456xyz",
    "output": {
        "hosted_connector": {
            "data": {
                "is_hit": true,
                "results": {
                    ...
                    "match_keys": "common_nickname,
                                  last_name,
                                  post_code,
                                  primary_contact_first_name,
                                  primary_contact_last_name",
                    ...
                },
            },
        },
    },
}

Example scenario

Search refinement: Imagine you have a number of data records all pointing to the same entity across one or many upstream Data APIs. Enter entity resolution, which uses the predefined keys to create a subset of records that belong to the same entity, in a accurate and trusted single view.

Contextual Data: Perhaps your customer has a number of subsidiaries at different customer lifecycle stages within your CRM. Entity resolution from Demyst can empower your KYB search by adding contextual data beyond matched keys to identify the right subsidiary. This may further enhance decision-making by uncovering hidden risks or opportunities.