File-based UID Matching

File-based UID Matching

Matching Overview


  1. You will upload a file containing a list of your UIDs to the S3 bucket in the appropriate inbox directory
  2. ID5 will process the file and return to the outbox in the S3 bucket a new file with a list of your match partner’s UIDs for every user we could match
ID5’s file-transfer matching protocol converts a file containing a list of your UIDs to a file containing the equivalent list of UIDs for one or more Match Partners. Available Match Partners are defined by contract between you and ID5. To change the list of Match Partners, please reach out to your ID5 representative.

ID5 creates inbox and outbox folders in the shared S3 bucket. Files to be processed must be uploaded into the inbox folder within a sub-directory for the match partner you would like to match to, and named with the extension .csv. The sub-directory should be named by the match partner’s Global Vendor List ID. A scheduled task will process the inbox files and create a file containing Match Partner UIDs with an identical name in the outbox folder within a sub-directory for the match partner. The original file will be moved within a processing directory when the job is started and will remain untouched and in its original form. You may delete these files at any point.
We recommend that files be named with the date and your internal segment id to ensure they are unique.
Any file pushed into the inbox will be fully processed only once and updates to the same file will not be processed.

Directory Structure

One directory within the inbox and outbox will be created for each Match Partner, containing the corresponding list of UIDs for this platform. The Match Partner directories will be named based on the partner’s Global Vendor List ID.

We also support using the ID5 Account Number instead of the GVL ID, prefaced by ID5- (e.g. ID5-43). Reach out to us if you’d like to use this method so we can give you your Match Partners’ ID5 Account Numbers.
S3://[bucket]/inbox/[match partner A GVL ID]/20180128_mysegmentidA.csv
S3://[bucket]/inbox/[match partner A GVL ID]/20180129_mysegmentidA.csv
S3://[bucket]/inbox/[match partner B GVL ID]/20180129_mysegmentidB.csv
 
## the above files will be processed as ##
 
S3://[bucket]/outbox/[match partner A GVL ID]/20180128_mysegmentidA.csv
S3://[bucket]/outbox/[match partner A GVL ID]/20180129_mysegmentidA.csv
S3://[bucket]/outbox/[match partner B GVL ID]/20180129_mysegmentidB.csv

File Format

Inbox

Column
Type
Description
UIDStringYour UID for this user
The maximum file size for inbox files is 1GB. If your files are larger, please split them before uploading or they may not be processed correctly.

Outbox

Matched Users Only

Generally, the outbox contains a single column containing the user IDs of the Match Partner that were requested. This is the default for all File-based UID Matching clients.
Column
Type
Description
UIDStringMatch Partner's UID for this user

Pairs Output

In some cases, clients will get access to the "pair" and not just the Match Partner IDs that were requested. In this case, the output contains both the original User ID you requested and, if matched, the Match Partner's User ID, separated by a |. Enabling this setting has a commercial impact, so please speak to your Account Manager if you'd like to discuss this integration method.
Column
Type
Description
UIDStringYour UID for this user
UIDStringMatch Partner's UID for this user

Example Files

Inbox Sample

$ cat ./inbox/8/20180128_mysegmentidA.csv
4822467914551922867
4700461554370241491
4572858233646453041
5952365002187240239
3896410401262240413
3827513351211796092

Outbox Sample

Matched Users Only

$ cat ./outbox/8/20180128_mysegmentidA.csv
49240e08-8de6-4deb-b060-6867684a3fd2
9aafa5ab-d867-4e1c-b4e3-1be6747ab097
a6b47ef8-7957-437f-a5fc-d0077399b1ee
06bf16ce-1fd9-4dca-849d-8144c887ad35
eddee745-33a8-49ed-ae63-1707fee2f393
76692099-fc23-4824-a6f8-3b8c60550c6b

Pairs Output 

$ cat ./outbox/8/20180128_mysegmentidA.csv
4822467914551922867|eddee745-33a8-49ed-ae63-1707fee2f393
4700461554370241491|9aafa5ab-d867-4e1c-b4e3-1be6747ab097
4572858233646453041|49240e08-8de6-4deb-b060-6867684a3fd2
5952365002187240239|06bf16ce-1fd9-4dca-849d-8144c887ad35
3896410401262240413|76692099-fc23-4824-a6f8-3b8c60550c6b
3827513351211796092|a6b47ef8-7957-437f-a5fc-d0077399b1ee

Reverse UID Lookups

If you need to convert a list of your Match Partners’ UIDs to your own (rather than converting your UIDs to your Match Partners’ as detailed above), you can simply adjust the names of root directories listed to the following: inbox-r, outbox-r, and processing-r. You can use both sets of directories in parallel if you have different use cases for different partners. All directory structures, file formats, and processes, other than the names of the three root directories previously mentioned, remain the same for both.

Cleaning Up / Deleting Old Files

By default, ID5 does not delete any files we place in the S3 bucket. Once you have processed a file in the outbox, you may delete it. You may also wish to delete files in the processing directory once all match jobs have been completed. However, if you remove an in-progress file from processing before the job is complete, the job may fail or have only partial results.