Perform Identity Resolution Through ADX

LiveRamp’s Identity Resolution in the Amazon Data Exchange (ADX) allows you to resolve personally-identifiable information (PII) or device identifiers to RampIDs, LiveRamp’s persistent pseudonymous identifier for persons and households. Identity resolution allows you to have a more holistic view of your data at an individual or household level.

Note

This article contains information on performing identity resolution with LiveRamp’s Identity offerings through ADX standalone. If you plan to perform identity resolution using AWS Entity Resolution, see “Perform Identity Resolution Using AWS Entity Resolution".
For more information about RampIDs, see "RampID Methodology".

You can also input an individual-based RampID and get back any household-based RampID that might be associated with that individual.

You can access LiveRamp Identity Resolution within the AWS Marketplace, meaning identity resolution can be performed within AWS. For more information on LiveRamp Identity in ADX, see “LiveRamp Identity in the ADX Marketplace”.

This service leverages LiveRamp’s Identity Graph, connecting fragmented consumer touchpoints to a person or household-based view.

The following identifiers can be resolved:

Names
Postal addresses
Email addresses
Phone numbers
Cookies
MAIDs (mobile device IDs)
CTV IDs (Connected TV Device IDs)
CIDs (custom identifiers)
Person-based, maintained RampIDs (for resolution to household RampIDs)

Based on the type of identifier you’re resolving, you might receive one RampID per identifier or multiple RampIDs per identifier:

For PII touchpoints (in PII or email resolution), you can choose to receive from 1 to 10 RampIDs (if available).
For PII touchpoints, you can also choose a deconfliction configuration that will return RampIDs that are ranked most relevant based on how active the linkages are in the digital ecosystem and other factors. This can be particularly useful for large data sets where overconnected RampIDs can introduce noise into analytics. For more information, see the “Deconfliction Options” section below.
Typically for cookie and mobile device ID resolution, one RampID is returned (but shared touchpoints with more than one RampID can exist).
For CTV identifiers it is common to receive multiple individual RampIDs per identifier.
For CIDs, the number of RampIDs will vary.
When resolving individual RampIDs to household RampIDs, only one household RampID is returned.

Deconfliction Options

Deconfliction is needed for analytics use cases and works best against universe datasets, meaning the full customer view across CRM-based data, subscriber data, or transaction data. These are typically large datasets, and because of the number of different touchpoints included (address, email, phone) and the sharing of touchpoints among consumers, one record in your dataset might match to some RampIDs in the LiveRamp Identity Graph that are also connected to other consumers (such as family members or relatives). This creates identity conflicts because some of these RampIDs might match to other records in your systems. These conflicts are the inevitable result of the sharing of devices, the use of multiple email addresses (and the sharing of email addresses), and other similar consumer behavior.

For certain use cases, you might want to include as many RampIDs as possible to maximize match and reach, and for these, deconfliction is not recommended. However, for other use cases, such as measurement, you might want to minimize noise across first-party datasets and the deconfliction configuration enables tuning of the outputs to maximize accuracy and fit the LiveRamp graph to your universe. This can be particularly useful for large datasets where overconnected RampIDs can introduce noise into analytics. Some use cases that benefit from this configuration are closed loop measurement, reach and frequency, or mutually exclusive segments as examples.

Using deconfliction on large universe datasets can help match your records to the RampIDs that are determined to be the most relevant for each record by looking at the strength of the connection of each RampID to each touchpoint. It includes references to how active the linkage is in the digital ecosystem.

To utilize deconfliction, you’ll need to provide a CID (custom ID) for each record, and for the configuration to drive the highest value, the full universe is required to deconflict across the table. The output you receive will include the best fidelity RampIDs for each CID.

There are two deconfliction options you can choose from:

Standard: This configuration returns the RampIDs that are determined to be most relevant and removes CIDs that are determined to be duplicates (based on linking to the same RampID). This is the default option and covers most advertiser use cases.
Maximized first-party fidelity: This configuration returns the RampIDs that are determined to be most relevant but preserves additional CIDs even if there are RampIDs that indicate LiveRamp could consolidate them. This option is ideal for publishers and other data owners.

Overall Steps

Before you can perform identity resolution, you must perform the steps to enable LiveRamp Identity in the ADX Marketplace. For information on performing these steps, see “LiveRamp Identity in the ADX Marketplace”.

After you’ve performed the steps to enable LiveRamp Identity in ADX, perform the following steps to perform identity resolution:

Note

To avoid errors, you might want to verify that your setup has been performed correctly before performing the operation. For more information, see the "Checklist to Verify Your Setup for LiveRamp Identity in ADX" section below.

Format the appropriate input data file and load it into your AWS S3 input location.
Initiate identity resolution by calling the LiveRamp Workflows API endpoint.
Initiate output file delivery by calling the LiveRamp Polling API endpoint.

After you initiate file delivery, LiveRamp delivers the resolved output file(s) to the specified S3 output location and associated usage metrics are reported to AWS for billing.

See the sections below for more information on performing these steps.

Checklist to Verify Your Setup for LiveRamp Identity in ADX

To avoid errors, use the checklists in the sections below to verify that all the necessary native app setup steps have been successfully performed before executing an operation.

AWS Region Alignment

Region in Contract: Confirm that the AWS region you provided to LiveRamp during contract execution is consistent with your actual AWS services.
AWS CLI Region Check: Run aws configure get region to verify the AWS region for the IAM user or profile you're using.

Note

The ADX offer will be made and accepted in US-East-2 and API calls will be made from US-East-2.
The region you provide for your contract is where your buckets need to be. As long as your buckets are in US-East-1, your job (compute at LiveRamp's end for your job) will run in US-East-1 and will not incur cross-region data transfer costs. For bucket regions other than US-Eeast-1 and US-West-2, you need cross region to be true in your incoming request and it will run in US-East-1.

IAM User and Permissioning

IAM User for ADX: Confirm that there is an IAM user configured specifically for ADX operations.
ADX Permissioning: Confirm that the IAM user has the required permissions for starting and polling jobs in ADX.
S3 Bucket Permissioning: Confirm that the IAM user has been granted read and write permissions for both the input and output S3 buckets.

S3 Bucket Setup

Input Bucket Configuration: Confirm that there is an S3 bucket exclusively dedicated for input files for LiveRamp processing.
Output Bucket Configuration: Confirm that there is a separate S3 bucket dedicated for output files from LiveRamp processing.
Bucket Policy Verification: Confirm that the bucket policies for the input and output buckets are aligned with LiveRamp's required permissions.
Bucket Accessibility Test: Execute aws s3 ls s3://<input-bucket-name> and aws s3 ls s3://<output-bucket-name> to verify IAM user access to the buckets.

Format the Input Data File

See the sections below for information on formatting the input data file.

Input File Formatting Guidelines

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

Include a header row in the first line of every file. Files cannot be processed without headers.
Include only one of the following allowed identifier types per file:
- PII
  - Names
  - Postal addresses
  - Plaintext email addresses
  - Phone numbers
- Hashed email addresses (SHA256, MD5, or SHA1)
- Cookies
- Mobile device IDs (MAIDs)
- CTV IDs
- CIDs (custom identifiers)
- Individual maintained RampIDs
  Note
  If the input file contains individual RampIDs, the RampIDs will be resolved to household RampIDs.
You can name your columns however you want, but every column name must be unique in a table.
Column names must be alphanumeric (other than underscores) and start with a letter.
Do not use spaces in column names. Use underscores.
The first column(s) in the input file must be the column(s) that contain the identifiers to be resolved.
When performing identity resolution on multiple files in one job, make sure the identifier column headers are the same in every file and that they match the value given for the “target_column” parameter in the call to initiate identity resolution.
Only one identity resolution operation is permitted per file, so only include one identifier type per file.
Try not to include additional columns. Having extra columns slows down processing.
Note
For device or CID resolution, or for workflows that involve deconfliction, additional columns (such as attribute data columns) can be included in the input file, but only the input identifiers and RampIDs will be returned in the output file. For PII or email resolution, any additional columns will be returned in the output file, but the identifiers will be removed and the row order randomized.
Formatting device identifiers:
- Cookies: Do not modify (for example, by changing casing) cookie values.
- Mobile device IDs:
  - Mobile device IDs should be downcased and hyphenated. For example: 1f4d256c-1f08-41f6-a108-bbe511de9497
  - Plaintext AAID and IDFA can be included together. LiveRamp can match off of both IDs at the same time as long as they are in plaintext.

File Format for PII Resolution (Without Deconfliction)

The standard PII resolution process (without deconfliction configured) passes the data through a privacy filter which removes the PII and reswizzles the table. Because of this, any attributes you need to keep associated with the identifier need to be included in the input table. For more information, see the "Privacy Filter" section below.

Note

Utilizing hashed attributes requires a LiveRamp Data Ethics review and an attestation. We will also work with your team to confirm separation of known and pseudonymous data prior to enabling permissions.

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

RampID
__lr_rank
__lr_filter_ name

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

Suggested Column Name	Example	Notes
`first_name`	John	You can include separate First Name and Last Name columns or you can combine first name and last name in one column (such as “Name”).
`last_name`	Doe	You can include separate First Name and Last Name columns or you can combine first name and last name in one column (such as “Name”).
`address_1`	123 Main St
`address_2`	Apt 1	You can include separate Address 1 and Address 2 columns or you can combine all street address information in one column (such as “Address”).
`city`	Smalltown	When matching on address, City is optional.
`state`	CA	When matching on address, State is optional. If including State, must be a two-character, capitalized abbreviation ("CA", not "California" or "Ca").
`zip`	12345	Required when matching on addresses. Can be in 5-digit format or 9-digit format (ZIP+4).
`email`	john@email.com	Plaintext emails only. Only one email per input row is permitted. Other emails must be dropped or included in an additional row. If you include an additional row, repeat the values for the name fields for the best match rates. All emails must meet these requirements: Have characters before and after the “@” sign Contain a period character (“.”) Have characters after the period character Examples of valid emails include: a@a.com A@A.COM email@account.com EMAIL@ACCOUNT.COM email@sub.domain.com EMAIL@SUB.DOMAIN.COM
`phone`	555-123-4567	Plain text phone numbers only. Only one phone number per input row is permitted. Other phone numbers must be dropped or included in an additional row. If you include an additional row, repeat the values for the name fields for the best match rates. All phone numbers must meet these requirements: Can be more than 10 characters if leading numbers over 10 characters are “0” or “1” If no leading numbers are used, must be 10 characters long Can contain hyphens (“-”), parentheses (“(“ or “)”), plus signs (“+”), and periods (“.”) Examples of valid phone numbers include: 8668533267 866.853.3267 (866) 853-3267 8668533267 +1 (866) 853-3267 +18668533267 18668533267 1111111118668533267 08668533267 Examples of invalid phone numbers include: 987654321 (fewer than 10 characters) 98765432109 (more than 10 characters) 1234567890 (after removing the leading “1”, less than 10 characters remain) 0987654321 (after removing the leading “0”, less than 10 characters remain)
`attribute_1`	Gender	For PII resolution, you can include columns with attribute data. These columns will be returned in the output file (for more information, see the "Output File for PII Resolution (Without Deconfliction)" section below). If you specify that an attribute column should be hashed, it will appear in the output table with a prefix of "hashed_". The input table must not include a column with the same name as the name of the hashed column in the output table.

File Format for PII Resolution (With Deconfliction)

This process allows for resolution of PII touchpoints with a deconfliction step, minimizing conflicts across the entire dataset. The output from this process is a deconflicted CID to RampID mapping.

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

Note

You can include columns with attribute data, but these columns will not be returned in the output table.

Suggested Column Name	Example	Notes
`cid`	g221lariab la8;blNj10gtQjQ3QUEwMTNEMTcaktboEc0g9022cxoiaklr91054	A custom identifier that represents an individual in the dataset. Data format is UTF-8 compliant alphanumeric string of up to 256 characters.
`first_name`	John	You can include separate First Name and Last Name columns or you can combine first name and last name in one column (such as “Name”).
`last_name`	Doe	You can include separate First Name and Last Name columns or you can combine first name and last name in one column (such as “Name”).
`address_1`	123 Main St
`address_2`	Apt 1	You can include separate Address 1 and Address 2 columns or you can combine all street address information in one column (such as “Address”).
`city`	Smalltown	When matching on address, City is optional.
`state`	CA	When matching on address, State is optional. If including State, must be a two-character, capitalized abbreviation ("CA", not "California" or "Ca").
`zip`	12345	Required when matching on addresses. Can be in 5-digit format or 9-digit format (ZIP+4).
`email`	john@email.com	Plaintext emails only. Only one email per input row is permitted. Other emails must be dropped or included in an additional row. If you include an additional row, repeat the values for the name fields for the best match rates. All emails must meet these requirements: Have characters before and after the “@” sign Contain a period character (“.”) Have characters after the period character Examples of valid emails include: a@a.com A@A.COM email@account.com EMAIL@ACCOUNT.COM email@sub.domain.com EMAIL@SUB.DOMAIN.COM
`phone`	555-123-4567	Plain text phone numbers only. Only one phone number per input row is permitted. Other phone numbers must be dropped or included in an additional row. If you include an additional row, repeat the values for the name fields for the best match rates. All phone numbers must meet these requirements: Can be more than 10 characters if leading numbers over 10 characters are “0” or “1” If no leading numbers are used, must be 10 characters long Can contain hyphens (“-”), parentheses (“(“ or “)”), plus signs (“+”), and periods (“.”) Examples of valid phone numbers include: 8668533267 866.853.3267 (866) 853-3267 8668533267 +1 (866) 853-3267 +18668533267 18668533267 1111111118668533267 08668533267 Examples of invalid phone numbers include: 987654321 (fewer than 10 characters) 98765432109 (more than 10 characters) 1234567890 (after removing the leading “1”, less than 10 characters remain) 0987654321 (after removing the leading “0”, less than 10 characters remain)

File Format for Email-Only Resolution (Without Deconfliction)

The standard email-only resolution process (without deconfliction configured) operates similarly to PII resolution. Any attributes you need to keep associated with the identifier need to be included in the input table. For more information, see the "Privacy Filter" section below.

Note

When resolving email data only, using email-only resolution can provide higher throughput compared to full PII resolution. Talk with your LiveRamp team to determine the best approach for your use case.
To perform identity resolution across additional PII touchpoints, see the “File Format for PII Resolution (Without Deconfliction)” section above.

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

Suggested Column Name	Example	Description
`hashed_email`	8c9775a5999b5f0088008c0b26d7fe8549d5c80b0047784996a26946abac0cef	SHA-256, MD5, and SHA-1 hashed emails accepted. Email addresses should be lowercased and UTF-8 encoded prior to hashing. After hashing, convert the resulting hash into lowercase hexadecimal representation.
`attribute_1`	Male	For email address resolution, you can include columns with attribute data. These columns will be returned in the output table (for more information, see the "Privacy Filter" section below).

File Format for Email-Only Resolution (With Deconfliction)

This process allows for resolution of touchpoints with a deconfliction step, minimizing conflicts across the entire dataset. The output from this process is a deconflicted CID to RampID mapping.

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

Note

You can include columns with attribute data, but these columns will not be returned in the output table.

Suggested Column Name	Example	Description
`cid`	g221lariab la8;blNj10gtQjQ3QUEwMTNEMTcaktboEc0g9022cxoiaklr91054	A custom identifier that represents an individual in the dataset. Data format is UTF-8 compliant alphanumeric string of up to 256 characters
`hashed_email`	8c9775a5999b5f0088008c0b26d7fe8549d5c80b0047784996a26946abac0cef	SHA-256, MD5, and SHA-1 hashed emails accepted. Email addresses should be lowercased and UTF-8 encoded prior to hashing. After hashing, convert the resulting hash into lowercase hexadecimal representation.

File Format for Device ID Resolution

The device ID resolution operation can be used for the following purposes:

To translate device identifiers (cookies, MAIDs, and CTV IDs) into individual RampIDs
To translate individual RampIDs into their associated household RampIDs

See the tables below for a list of the suggested input file columns and descriptions for these device ID resolution options.

Note

Each device ID resolution input file should contain only one identifier column (either a device identifier or a maintained RampID).
You can include columns with attribute data, but these columns will not be returned in the output file.

See the table below for a list of the suggested input file columns and descriptions for translating device identifiers.

Suggested Column Name	Example	Description
`device_identifier`	1f4d256c-1f08-41f6-a108-bbe511de9497	Can be one of the following identifiers: Cookie MAID CTV ID

See the table below for a list of the suggested input table columns and descriptions for translating individual RampIDs into their associated household RampIDs.

Suggested Column Name	Example	Description
`RampID`	XYT999wXyWPB1SgpMUKlpzA013UaLEz2lg0wFAr1PWK7FMhsd	The RampID for translation to a Household RampID. Must be a maintained RampID (to have an associated with a Household RampID).

File Format for CID Matching

This process enables the retrieval of an existing CID to RampID mapping.

See the table below for a list of the suggested input file columns and descriptions for CID matching.

Note

You can include columns with attribute data, but these columns will not be returned in the output file.

Suggested Column Name	Example	Description
`cid`	b916clarib la1;blNj10gtQjQ3QUEwMTNEMTcaktboEc0g9022cxoiaklr20185	The CID for translation to a RampID

Initiate Identity Resolution

Once your data files have been prepared and placed into your S3 bucket, initiate the identity resolution process. This is done by making a call with the AWS CLI to the LiveRamp Workflows ADX API that follows the format of the examples shown below.

Note

For information on the parameters to include in the call, see the “API Parameters” section below.
Only include the match_limit parameter for PII or email resolution (without deconfliction configured), where you want to specify the maximum number of RampID results returned per input identifier (default is “1”).
Only include the input_columns parameter for email or PII resolution. This is where you will specify which columns are the target_column(s) and any attribute columns you wish to pass through to the output table.
Only include the target_columns parameter for PII resolution. Use this parameter to specify the target PII columns to use for identity resolution. When using the target_columns parameter, do not include the target_column parameter.
Note
For execution types other than PII resolution, use the target_column parameter instead of target_columns.
For information on troubleshooting errors that might occur when performing calls, see "Troubleshoot Calls in ADX".

Once you've received a successful response, make a poll job request to initiate the delivery of the output file to the output S3 bucket (for more information, see the "Initiate Output File Delivery" section below).

AWS CLI Calls to Initiate Identity Resolution

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 \
  --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 an example of what a populated AWS CLI call to initiate translation might look like:

Examples of AWS CLI Calls

See below for examples of AWS CLI calls.

PII Resolution Call Example (Without Deconfliction)

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --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",
                                    "hashedAttributes": ["CID"]
                                  },
                "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"
            }'

PII Resolution Call Example (With Deconfliction)

aws dataexchange send-api-asset \
--data-set-id <data-set-id> \
--revision-id <revision-id> \
--asset-id <asset-id> \
--method POST \
--path "/adx/job/start" \
--body '{
"input_s3": "s3://my-input-bucket-name",
"file_format": "csv",
"file_pattern": "cid_mapping_input[.]csv",
"workflow_type": "resolution",
"workflow_sub_type" : "CID_MAPPING",
"target_columns": {
"name": ["FIRSTNAME", "LASTNAME"],
"address": ["ADDRESSLINE", "ADDRESSLINE2"],
"city": "CITY",
"state": "STATE",
"zip": "ZIPCODE",
"email": "EMAIL",
"phone": "PHONE",
"cid": "CID"
},
"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",
"LIKES_DOGS": "text",
"CID": "text"
},
"cross_region": "true",
"config": {"deconflictionConfig": "STANDARD"}
}'

Email Resolution Call Example (Without Deconfliction)

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --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"
            }'

CTV ID Resolution Call Example

aws dataexchange send-api-asset \
    --data-set-id <data-set-id> \
    --revision-id <revision-id> \
    --asset-id <asset-id> \
    --method POST \
    --path "/adx/job/start" \
    --body '{
                "input_s3": "s3://my-input-bucket-name",
                "file_format": "csv",
                "file_pattern": "ctv_input[.]csv",
                "workflow_type": "resolution",
                "workflow_sub_type": "CTV",
                "target_column": "my_ctv_column",
                "client_id": "my-client-id",
                "client_secret": "my-client-secret",
                "cross_region": "true"
            }'

Example Responses for Calls to Initiate Resolution

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).

Note

For information on troubleshooting errors that might occur when performing calls, see "Troubleshoot Calls in ADX".

Initiate Output File Delivery

Once you’ve initiated the identity resolution process, you must make a poll job request to initiate the delivery of the output file to the output S3 bucket after processing is complete. One of the parameters you'll need to make that call is the Job ID that was included in the response to the call to initiate identity resolution.

Note

For information on the parameters to include in the call, see the “API Parameters” section below.
It is recommended that polling be done programmatically at recurring intervals until the processing is complete and the output file has been delivered.
For information on troubleshooting errors that might occur when performing calls, see "Troubleshoot Calls in ADX".

AWS CLI Calls to Initiate Delivery

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 \
    --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 \
    --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"
            }'

Example Responses for Calls to Initiate Delivery

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:

''Upload to AWS S3 in progress. Re-poll later or wait for the delivery notification'
'Output results uploaded to AWS S3 bucket'

Note

For information on troubleshooting errors that might occur when performing calls, see "Troubleshoot Calls in ADX".

API Parameters

See the tables below for a list of the API header parameters and request parameters.

Header Parameters

Header Parameter	Data Type	Description
data-set-id	string	Your AWS-provided Data set ID.
revision-id	string	Your AWS-provided Revision ID.
asset-id	string	Your AWS-provided Asset ID.

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

Request Parameters

Request Parameter	Description
client_id	Either an existing LiveRamp client ID (if you already have Identity API credentials) or a new one provided by LiveRamp
client_secret	Password / secret for the LiveRamp client_ID (either an existing password / secret (if you already have Identity API credentials) or a new one provided by LiveRamp)
workflow_type	“resolution” for all identity resolution processes
workflow_sub_type	The type of identifiers being resolved. Options include: `PII` `Email` `Cookies` `MAID` `CTV` `CID_MAPPING` (creation of the CID sync with deconfliction) `CID` (provided to you by LiveRamp and specific to an existing mapping) `HHLink` (to resolve individual RampIDs into household RampIDs) Note Each identifier type has to be separated into its own input table (including CID types) and only one option above can be chosen for each operation.
input_s3	S3 directory for input files.
output_s3	S3 directory for output files.
file_format	Specifies the format for input files. Accepted file format is "csv".
file_pattern	Regex pattern for input files. For example, the pattern ‘input_2.*[.]csv’ would result in the processing of the following files: input_20.csv input_221.csv input_225.csv
target_column	The column header name for the input field which contains the IDs to be resolved. Ex: “DEVICE_ID” Note For PII resolution (with our without deconfliction), leave this parameter out.
input_columns	For PII or email workflows, this includes the target column and any attribute columns you want to pass through into the output table. For example: "input_columns": { "hashed_email": "text", "gender": "text", "last_car": "text" } Note For PII resolution, these column names cannot be used in the input table: RampID __lr_rank __lr_filter_ name
target_columns	A subset of input_columns used in PII resolution jobs. These are the PII elements that will be resolved to create the output RampIDs. "target_columns": { "name": ["name"], "streetAddress": ["address"], "zipCode": "zip", "phone": "phone", "email": "email", "hashedAttributes": ["cid"] } Note Do not include the name of attribute columns you want to pass through unhashed in this parameter. Use the `input_columns` parameter to include those attribute columns.
deconfliction_config	Specify the 'config' request parameter as an object with the type of deconfliction you want to execute for example, {"deconflictionConfig": "STANDARD"}" (for more information, see the "Deconfliction Options" section above). Accepted values include: `standard`: This configuration returns the RampIDs that are determined to be most relevant and removes CIDs that are determined to be duplicates (based on linking to the same RampID). This is the default option and covers most advertiser use cases. `maximized_1P_fidelity`: This configuration returns the RampIDs that are determined to be most relevant but preserves additional CIDs even if there are RampIDs that indicate LiveRamp could consolidate them. This option is ideal for publishers and other data owners.
cross_region	“true” or “false”. If “true”, then workloads are processed in the default region (us-east-1) if the target region is unavailable. If “false”, then workloads are not processed in the default region if the target region is unavailable and a status message to enable cross region is returned to the caller.
match_limit	For PII or email resolution only (without deconfliction), specify an integer between 1 and 10 to specify the maximum number of RampID results returned per input identifier (to return only the “best match”, returning 1 RampID is sufficient). The default is “1”.
job_id	For polling requests, enter the Job ID returned in the response for the call to initiate identity resolution. The Job ID consists of a unique ID plus your AWS region name.

View Identity Resolution Output

The output file(s) from the identity resolution process will be compressed and then written to the specified S3 bucket provided in the poll job request.

The file naming convention for the output file will be "<JOB_ID>_0_0_0.csv.gz"

The Job ID will be a unique ID plus your AWS region name.

Ex: 17697C67E98D4702BEB4ED7B3B0FA_AWS_US_EAST_1_0_0_0.csv.gz

Output File for PII Resolution (Without Deconfliction)

The standard PII resolution process (without deconfliction configured) passes the input table through a privacy filter which removes the PII and reswizzles the table (in addition to other operations). Because of this, any attributes you need to keep associated with the identifier need to be included in the input table. For more information, see the "Privacy Filter" section below.

Identity resolution of PII provides supplemental match metadata for additional insight into customer data that can provide powerful signals for making decisions based on RampIDs.

For PII resolution, the output table includes the fields shown in the table below.

Column	Sample	Description
`RampID`	XYT999wXyWPB1SgpMUKlpzA013UaLEz2lg0wFAr1PWK7FMhsd	Returns the resolved RampID in your domain encoding.
`attribute_1`	Male	Any attribute columns passed through the service are returned.
`hashed_cid`	63889cfb9d3cbe05d1bd2be5cc9953fd	Any hashed attribute columns passed through the service are returned with their values MD5 hashed.
`__lr_rank`	1	Provides insight on the match cascade level associated with the identifiers. If no maintained RampID is found, this value will be "null".
`__lr_filter_name`	name_phone	Returns the filter name where the match occurred, which will be one of the following options: `name_address_zip` `name_email` `name_phone` `partial_name_email` `partial_name_phone` `strict_name` (name + zip) `email` `phone` `last_name_address` If no maintained RampID is found, this value will be "null".

Output File for PII Resolution (With Deconfliction)

For PII resolution with deconfliction, the output table includes the fields shown in the table below.

Column	Example	Description
`hashed_cid`	93abc799-a0a5-40b5-80dd-d2ab61d4d072	The CID passed into the process will be returned as an MD5-hashed CID.
`RampID`	XYT999wXyWPB1SgpMUKlpzA013UaLEz2lg0wFAr1PWK7FMhsd	Returns the resolved and deconflicted RampID in your domain encoding.

Output File for Email Address Resolution (Without Deconfliction)

For email resolution, the output table includes the fields shown in the table below.

Column	Example	Description
`RampID`	XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD	The RampID associated with the email address. Note If multiple RampIDs are associated with an email address, multiple lines will be created in the output file.
`attribute_1`	Male	The original attribute columns included in the input file.

Output File for Email Address Resolution (With Deconfliction)

For email resolution with deconfliction, the output table includes the fields shown in the table below.

Column	Example	Description
`hashed_cid`	93abc799-a0a5-40b5-80dd-d2ab61d4d072	The CID passed into the process will be returned as an MD5-hashed CID.
`RampID`	XYT999wXyWPB1SgpMUKlpzA013UaLEz2lg0wFAr1PWK7FMhsd	Returns the resolved and deconflicted RampID in your domain encoding.

Output File for Device ID Resolution

The output file for device ID resolution will follow the format shown in the table below.

Column	Example	Description
`device_identifier` OR `RampID`	1f4d256c-1f08-41f6-a108-bbe511de9497	The original identifier included in the input file.
`RampID`	XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD	For input files containing device identifiers,the RampID associated with the device identifier. For input files containing individual RampIDs, the household RampIDs associated with those individual RampIDs. Note: If multiple RampIDs are associated with a device identifier, multiple lines will be created in the output file.

Column

Example

Description

device_identifier OR RampID

1f4d256c-1f08-41f6-a108-bbe511de9497

The original identifier included in the input file.

RampID

XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD

For input files containing device identifiers,the RampID associated with the device identifier.

For input files containing individual RampIDs, the household RampIDs associated with those individual RampIDs.

Note: If multiple RampIDs are associated with a device identifier, multiple lines will be created in the output file.

Output File for CID Matching

The output file for CID matching will follow the format shown in the table below.

Column	Example	Description
`cid`	93abc799-a0a5-40b5-80dd-d2ab61d4d072	The original identifier included in the input file.
`RampID`	XYT999RkQ3MEY1RUYtNUIyMi00QjJGLUFDNjgtQjQ3QUEwMTNEMTA1CgMjVBMkNEMTktRD	The resolved RampID in your domain encoding.

Privacy Filter

To minimize the risk of re-identification (the ability to tie PII directly to a RampID), the service includes the following processes when resolving PII identifiers (PII resolution or email-only resolution):

Column Values: The process evaluates the combination of all the column values on a per row basis for unique values. If a particular combination of column values occurs 3 or fewer times, the rows containing those column values will not be matchable and will not be returned in the output table.
Note
This check does not apply to hashed attributes.
>5% of the table unmatchable: If, based on column value uniqueness, >5% of the file rows are unmatchable, the job will fail.
Number of Unique RampIDs: If fewer than 100 unique RampIDs would be returned, the job will fail.
Reswizzle full table: Upon completion, the full table will be reswizzled to return the rows RampID | attribute_1 | attribute_2 | attribute_n in a different order than what was submitted in the input table.

Note

When using the deconfliction configuration, attributes are not preserved so the privacy filter is not applied.

In this section:

Perform Identity Resolution Through ADX

Note

Deconfliction Options

Overall Steps

Note

Checklist to Verify Your Setup for LiveRamp Identity in ADX

AWS Region Alignment

Note

IAM User and Permissioning

S3 Bucket Setup

Format the Input Data File

Input File Formatting Guidelines

Note

Note

File Format for PII Resolution (Without Deconfliction)

Note

File Format for PII Resolution (With Deconfliction)

Note

File Format for Email-Only Resolution (Without Deconfliction)

Note

File Format for Email-Only Resolution (With Deconfliction)

Note

File Format for Device ID Resolution

Note

File Format for CID Matching

Note

Initiate Identity Resolution

Note

Note

AWS CLI Calls to Initiate Identity Resolution

Examples of AWS CLI Calls

PII Resolution Call Example (Without Deconfliction)

PII Resolution Call Example (With Deconfliction)

Email Resolution Call Example (Without Deconfliction)

CTV ID Resolution Call Example

Example Responses for Calls to Initiate Resolution

Note

Initiate Output File Delivery

Note

AWS CLI Calls to Initiate Delivery

Example Responses for Calls to Initiate Delivery

Note

API Parameters

Header Parameters

Request Parameters

Note

Note

Note

Note

View Identity Resolution Output

Output File for PII Resolution (Without Deconfliction)

Output File for PII Resolution (With Deconfliction)

Output File for Email Address Resolution (Without Deconfliction)

Note

Output File for Email Address Resolution (With Deconfliction)

Output File for Device ID Resolution

Output File for CID Matching

Privacy Filter

Note

Note

Search results