--- title: "PII Segment Onboarding" canonical: "https://hub.freewheel.tv/space/BC/303628351/PII%20Segment%20Onboarding" format: markdown --- --- # Overview Buyer Cloud allows the upload of first-party, personally identifiable information (PII) through the UI. After you upload your PII segment in the UI, it is transferred to an AWS S3 bucket, where a match service appends Transunion IDs to the segments. The [PII Matching Logic](#PII-Matching-Logic) section below explains what information is prioritized when matching members. > ℹ️ Note for non-AWS clients: If your organization does not use AWS, please contact your account team to enable this functionality. The following PII types can be onboarded in Buyer Cloud: - First name - Last name - Street number and address (including city, state, and zip code) - Email address -all in lower case. Raw or or hashed are acceptable (must have be in lower case prior to hash). - Phone number > ℹ️ Segment Extension must be turned on whenever you target a PII-onboarded segment. --- # Format PII Onboard Files Segment files must meet the following requirements in order to be successfully onboarded into Buyer Cloud: - File Type: CSV (preferred) or Parquet - Compression: No compression preferred; gzip supported - Delimiters: Comma preferred - Encoding: UTF-8 or ASCII - One user ID per row (one sequence number or one customer ID). Each row is either one individual or one household depending on the data being uploaded. - The client_sequence_number is returned in matchback results to provide information on which records were matched. - Hashed or raw emails must be uploaded into the platform as lowercase. > ℹ️ PII segment onboarding supports up to 20 million total records. If you anticipate needing a higher cap, please contact your FreeWheel account representative to discuss options for increasing your allocation. Below is an example of the expected file format: ``` client_sequence_number,first_name,middle_name,last_name,emails,phone_numbers,addresses,segment_keys 123456,Janet,Jerry,Pierce,[[JanetJeremiahPierce, aol.com]],[[+1575, 047-3238]],[[386, , 13th Street, , Bellevue, PR, 13754]],BUZZKEY-12313 ``` The address column contains an array of addresses. Each address must contain 8 comma-separated elements, including blanks where values are not provided. See the table below for examples. ``` Street Number, Pre-Directional, Street Name and Street type, Unit, City Name, State, Zip Code, Zip Code +4) ``` If zip4 is not available, leave that position empty but keep the comma so the array length stays consistent. ## PII Field Naming Conventions Below are details for the input types accepted for each PII field in the file upload: ***Required** | **Type** | **Column Name** | **Input Details** | **Input Example** | **Column nullable** | **Empty Value in csv file** | | --- | --- | --- | --- | --- | --- | | client_sequence_number* | `client_sequence_number` | A client-appended unique ID used to map matched or unmatched records back to their original CRM, enabling internal use cases. | `123456789012345` | No | N/A | | first Name | `first_name` | String | `JOHN` | Yes | ““ | | middle_name | middle_name | String | BOB | Yes | ““ | | last Name | `last_name` | String | `SMITH` | Yes | ““ | | emails | `emails` | An array of array of strings (up to 3 distinct)
Emails used by individual
Nested array with email prefix and domain as separate elements
Emails must be in lower case in all instances, including prior to hashing if hashing being used. | `“[  `
`[bobjsmith, gmail.com], [bsmith, gmail.com], [bsmith, yahoo.com]  `
`]” ` | Yes | “[]“ | | phone_numbers | phone_numbers | An array of array of strings (up to 3 distinct)
Phone numbers used by individual
Nested array with country code & area code and phone number as separate elements | “[
[+1917, 123-4567], [+1646, 123-4567], [+1212, 123-4567]
]” | Yes | “[]“ | | addresses | `addresses` | An array of array of strings (up to 3 distinct)
Addresses of individual
Nested array with the following address info as separate elements:
(Building Number, Pre-Directional, Street Name and Street type, Unit, City Name, State, Zip Code, Zip Code +4)
if an address element is not present include a space followed by a comma to delimit | `“[  `
`[243, W, 60TH ST, 2B, NEW YORK, NY, 10023, ],  `
`[39-01, W, MAIN ST, 2B, FLUSHING, NY, 11354,6789 ], [123, , MAIN ST, , ANYTOWN, CA, 12345, 6789]  `
`]” ` | Yes | “[]“ | | segment_keys | segment_keys | String of 1 or more segment keys or segment alternate IDs
The Segment key format for segments is `:|:|`, where the `` is in the format `-`. | stinger-123|stinger-456|stinger-789:100
**Or Alternate ID**
12345678|1003806829|2004907930:2.5 | No | N/A | --- # Onboard PII Segments in Buyer Cloud UI After your PII file is formatted according to the above specifications, to upload your PII segments directly in the Buyer Cloud UI, do the following: 1. First, create an empty segment shell in the **Segments **page to contain the PII segment upload. For a full walkthrough on segment shell creation, see [Create a Segment Shell for Segment Shell Uploads](https://freewheel-knowledge-hub.atlassian.net/wiki/spaces/BC/pages/114852102/Segments#Create-a-Segment-Shell-for-Segment-Uploads). 2. After creating the segment shell, go to the **Segment Uploads** page, and select the **New Segment Upload **dropdown. 3. On the New Segment Upload screen, set the **PII Segment** toggle to *Yes*, then fill out the following fields: | **Field Name** | **Description** | | --- | --- | | File Format | The format of the PII file to be uploaded.
.csv is strongly preferred, however, Parquet file types can accepted. | | Segment Key Type | The type of segment key used in the upload, as designated by the segment shell created in **Segments**. Options include default or alternate. | | PII Segment Toggle | Whether the segment contains PII.
> ℹ️ Set this field to *On *for PII segment onboarding. | | User ID Type | This defaults to *3rd Party ID* for PII segment onboarding. | | Continent | The continent where the segment users live. This field will default to North America, since PII segment upload is only available for US markets. | | File | The segment file to onboard. For file upload specifications, see the above [Format PII Onboard Files](#Format-PII-Onboard-Files) section. | 3. Select Upload & Save to upload your data to S3 and begin the match process. > ℹ️ To confirm the ID matching was successful, contact your account representative to open a ticket to get match results. --- # PII Matching Logic After segments are onboarded, the segment matching process finds and adds TransUnion IDs to members in the following priority order: 1. First name, last name, phone number, and email address. 2. First name, middle name, and phone number. 3. Phone number and email address. 4. First name, last name, and phone number. 5. Email address. 6. First name, middle name, and home address. If no ID match is found at this point, the match service identifies the member by a household-level fallback: 7. Last name and home address. 8. Home address.