Perform Known Identity Resolution Through ADX

Identity resolution input data files should be formatted as CSV files. When creating input data files, follow these additional guidelines:

Managing data in the known identity space does not require the same privacy protections as the pseudonymous RampID identity space and, as noted in prior sections, all attribute data included in the input table will pass through to the output table.

These column names cannot be used in the input file for PII resolution:

See the table below for a list of the suggested input file columns and descriptions for PII resolution.

The standard email-only resolution process operates similarly to PII resolution.

See the table below for a list of the suggested input table columns and descriptions for email-only resolution.

This set of optional metadata provides flags that can indicate whether a particular postal address, phone number, or email address is the primary one for that individual. Best Contact flags are Boolean operators (TRUE or FALSE) that indicate if the address, email, or phone that was sent matches the one that the Known Identity Graph has determined is the best one for that user.

Best contact flag use cases include:

If a record is used that includes all of the best touchpoints, we will return "true" for all three flags. These flags will be returned in a _lr_metadata column.

The "clickVerifyDate" flag is a signal that is used in designating the best email address for a user that could have other uses in building data assets or scoring email address data. Because this signal relies on specific deterministic signals from a small subset of LiveRamp match data contributors, it appears on a subset of "Best Email" addresses and should not be used as the only filter for understanding active email addresses.

These flags are only available for Known ID person-based identifiers.

Best contact flags include the information shown in the table below:

See below for the format of an AWS CLI call to initiate identity resolution:

aws dataexchange send-api-asset \
  --data-set-id <data-set-id> \
  --revision-id <revision-id> \
  --asset-id <asset-id> \
  --method POST \
  --region us-east-2 \
  --path "/adx/job/start" \
    --body '{
                "input_s3": "<Input S3 bucket>",
                "file_format": "csv",
                "file_pattern": "<Regex pattern for input files>[.]csv",
                "workflow_type": "resolution",
                "workflow_sub_type": "<Resolution sub type>",
                "target_column": "<Identifier column header>",
                "client_id": "<Client ID>",
                "client_secret": "<Client secret>",
                "input_columns": {<"Column name": "Column type">},
                "cross_region": "true"
            }'

See below for examples of what a populated AWS CLI call to initiate translation might look like.

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --region us-east-2 \
    --path "/adx/job/start" \
    --body '{
                "input_s3": "s3://my-input-bucket-name",
                "file_format": "csv",
                "file_pattern": "pii_input[.]csv",
                "workflow_type": "resolution",
                "workflow_sub_type" : "PII",
                "target_columns": {
                                    "name": ["FIRSTNAME", "LASTNAME"],
                                    "address": ["ADDRESSLINE", "ADDRESSLINE2"],
                                    "city": "CITY",
                                    "state": "STATE",
                                    "zip": "ZIPCODE",
                                    "email": "EMAIL",
                                    "phone": "PHONE",
                                  },
                "client_id": "my-client-id",
                "client_secret": "my-client-secret",
                "input_columns": {
                                    "FIRSTNAME": "text",
                                    "LASTNAME": "text",
                                    "ADDRESSLINE": "text",
                                    "ADDRESSLINE2": "text",
                                    "CITY": "text",
                                    "STATE": "text",
                                    "ZIPCODE": "text",
                                    "EMAIL": "text",
                                    "PHONE": "text",
                                    "CID": "text",
                                    "LIKES_DOGS": "text"
                                 },
                "cross_region": "true"
            }'
'limit': 1,
‘outputIdentifiers’:[
	“knownId”, 
	“householdLink”, 
	“placeId”
],
‘outputMetadata’:[
	“matchLevel”, 
	“rank”, 
	“isBestEmailTouchpoint”
],
'outputTable': $output_table_name
“targetColumns”: {
      "name": ["<up to 4 name column names>"],
      "streetAddress": ["<up to 7 address column names>"],
      "city": "<city column>",
      "state": "<state column>",
      "zipCode": "<zipcode column>",
      "phone": "<phone column>",
      "email": "<email column>",
    }
    }::variant as config;

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --region us-east-2 \
    --path "/adx/job/start" \
    --body '{
                "input_s3": "s3://my-input-bucket-name",
                "file_format": "csv",
                "file_pattern": "resolution_input_2.*[.]csv",
                "workflow_type": "resolution",
                "workflow_sub_type": "EMAIL",
                "target_column": "hashed_email",
                "client_id": "my-client-id",
                "client_secret": "my-client-secret",
                "input_columns": {
                                    "hashed_email": "text",
                                    "gender": "text"
                                 },
                "cross_region": "true"
            }'

The following is an example of a response for a successful job submission for a call to initiate identity resolution:

{
    "ResponseHeaders": {
        "Content-Type": "application/json",
        "Content-Length": "97",
        ...
    },
    "Body": "{\"Job ID\": \"E660EC80F3BF4473A120D3CAC890CADC_AWS_US_EAST_1\", \"Status\": \"ADX Start job submitted\"}"
}

Use the Job ID in the poll job request to initiate the delivery of the output file (for more information, see the "Initiate Output File Delivery" section below).

See below for the format of an AWS CLI call used to initiate output file delivery:

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --region us-east-2 \
    --path "/adx/job/poll" \
    --body '{
            "job_id": "<Job ID>",
            "output_s3": "<Output S3 bucket>",
            "file_format": "csv",
            "client_id": "<Client ID>",
            "client_secret": "<Client secret>",
            "cross_region": "true"
            }'

See below for an example of what a populated AWS CLI call used to initiate output file delivery might look like:

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --region us-east-2 \
    --path "/adx/job/poll" \
    --body '{
            "job_id": "JOB_ID_123",
            "output_s3": "s3://my-output-bucket",
            "file_format": "csv",
            "client_id": "my-client-id",
            "client_secret": "my-client-secret",
            "cross_region": "true"
            }'

The following is an example of a response when processing is complete:

{
    "ResponseHeaders": {
        "Content-Type": "application/json",
        "Content-Length": "158",
        ...
    },
    "Body": "{\"Job ID\": \"E660EC80F3BF4473A120D3CAC890CADC_AWS_US_EAST_1\", \"Status\": \"ADX Poll job started for delivering output results. Re-poll later for updated status\"}"
}

In addition to the response received when processing is complete, you might get one of the following responses in the status parameter:

For information on finding the AWS-provided parameters, see this AWS article.

For known resolution, the identifiers and metadata returned is configurable, as outlined in the "Initiate Identity Resolution" section above. Depending on the values included, the output file will vary based on the following:

For PII resolution, the default output file includes the columns shown in the table below.

For PII resolution, additional configurability options (such as including additional identifiers and including additional metadata) could produce an output file that includes the following:

The email-only resolution process operates similarly to PII resolution. For known resolution, the identifiers and metadata returned is configurable, as outlined in the "Initiate Identity Resolution" section above. Depending on the values included, the output file will vary based on:

For email-only resolution, the output file includes the columns shown in the table below.